@herdctl/core 0.0.1

package/src/state/directory.ts

@@ -0,0 +1,217 @@
+/**
+ * State directory management
+ *
+ * Provides functions to initialize and access the .herdctl/ state directory
+ */
+
+import { mkdir, stat, access, constants } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import {
+  type StateDirectory,
+  type InitStateDirectoryOptions,
+  type StateDirectoryValidation,
+  STATE_SUBDIRECTORIES,
+  DEFAULT_STATE_DIR_NAME,
+  STATE_FILE_NAME,
+} from "./types.js";
+import {
+  StateDirectoryCreateError,
+  StateDirectoryValidationError,
+  StateFileError,
+  getPermissionErrorMessage,
+} from "./errors.js";
+import { createInitialFleetState, FleetStateSchema } from "./schemas/index.js";
+import { atomicWriteYaml } from "./utils/index.js";
+import { safeReadYaml } from "./utils/reads.js";
+
+/**
+ * Get the paths for all state directory components
+ *
+ * @param rootPath - Root path to the state directory (e.g., /path/to/.herdctl)
+ * @returns StateDirectory object with paths to all subdirectories and files
+ */
+export function getStateDirectory(rootPath?: string): StateDirectory {
+  const root = rootPath
+    ? resolve(rootPath)
+    : resolve(process.cwd(), DEFAULT_STATE_DIR_NAME);
+
+  return {
+    root,
+    jobs: join(root, "jobs"),
+    sessions: join(root, "sessions"),
+    logs: join(root, "logs"),
+    stateFile: join(root, STATE_FILE_NAME),
+  };
+}
+
+/**
+ * Check if a path exists and is a directory
+ */
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a path exists (file or directory)
+ */
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate that the state directory structure exists and is accessible
+ *
+ * @param stateDir - StateDirectory object to validate
+ * @returns Validation result with any missing paths or errors
+ */
+export async function validateStateDirectory(
+  stateDir: StateDirectory
+): Promise<StateDirectoryValidation> {
+  const missing: string[] = [];
+  const errors: string[] = [];
+
+  // Check root directory
+  if (!(await isDirectory(stateDir.root))) {
+    const exists = await pathExists(stateDir.root);
+    if (exists) {
+      errors.push(`'${stateDir.root}' exists but is not a directory`);
+    } else {
+      missing.push(stateDir.root);
+    }
+  }
+
+  // Check subdirectories
+  for (const subdir of STATE_SUBDIRECTORIES) {
+    const subdirPath = stateDir[subdir];
+    if (!(await isDirectory(subdirPath))) {
+      const exists = await pathExists(subdirPath);
+      if (exists) {
+        errors.push(`'${subdirPath}' exists but is not a directory`);
+      } else {
+        missing.push(subdirPath);
+      }
+    }
+  }
+
+  // Check state file (should exist, can be file)
+  if (!(await pathExists(stateDir.stateFile))) {
+    missing.push(stateDir.stateFile);
+  }
+
+  return {
+    valid: missing.length === 0 && errors.length === 0,
+    missing,
+    errors,
+  };
+}
+
+/**
+ * Create a single directory with descriptive error handling
+ */
+async function createDirectory(path: string): Promise<void> {
+  try {
+    await mkdir(path, { recursive: true });
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    throw new StateDirectoryCreateError(
+      getPermissionErrorMessage(code, path),
+      path,
+      error as Error
+    );
+  }
+}
+
+/**
+ * Initialize the state directory structure
+ *
+ * Creates the .herdctl/ directory and its subdirectories (jobs/, sessions/, logs/)
+ * if they don't exist. Also creates an initial state.yaml file with empty fleet state.
+ *
+ * @param options - Options for initialization
+ * @returns StateDirectory object with paths to all subdirectories
+ * @throws {StateDirectoryCreateError} If directories cannot be created
+ * @throws {StateFileError} If state.yaml cannot be created
+ *
+ * @example
+ * ```typescript
+ * // Initialize in current directory
+ * const stateDir = await initStateDirectory();
+ *
+ * // Initialize in custom location
+ * const stateDir = await initStateDirectory({ path: '/custom/path/.herdctl' });
+ * ```
+ */
+export async function initStateDirectory(
+  options: InitStateDirectoryOptions = {}
+): Promise<StateDirectory> {
+  const stateDir = getStateDirectory(options.path);
+
+  // Create root directory
+  await createDirectory(stateDir.root);
+
+  // Create subdirectories
+  for (const subdir of STATE_SUBDIRECTORIES) {
+    await createDirectory(stateDir[subdir]);
+  }
+
+  // Create state.yaml if it doesn't exist
+  if (!(await pathExists(stateDir.stateFile))) {
+    try {
+      const initialState = createInitialFleetState();
+      await atomicWriteYaml(stateDir.stateFile, initialState);
+    } catch (error) {
+      throw new StateFileError(
+        `Failed to create initial state file: ${(error as Error).message}`,
+        stateDir.stateFile,
+        "write",
+        error as Error
+      );
+    }
+  } else {
+    // Validate existing state.yaml is readable and valid
+    const result = await safeReadYaml(stateDir.stateFile);
+    if (!result.success) {
+      throw new StateFileError(
+        `Existing state file is corrupted or unreadable: ${result.error.message}`,
+        stateDir.stateFile,
+        "read",
+        result.error
+      );
+    }
+
+    // Validate against schema
+    const parseResult = FleetStateSchema.safeParse(result.data);
+    if (!parseResult.success) {
+      const issues = parseResult.error.issues
+        .map((i) => `${i.path.join(".")}: ${i.message}`)
+        .join("; ");
+      throw new StateFileError(
+        `Existing state file has invalid schema: ${issues}`,
+        stateDir.stateFile,
+        "read"
+      );
+    }
+  }
+
+  // Final validation
+  const validation = await validateStateDirectory(stateDir);
+  if (!validation.valid) {
+    const allIssues = [...validation.missing, ...validation.errors];
+    throw new StateDirectoryValidationError(
+      `State directory validation failed: ${allIssues.join(", ")}`,
+      validation.missing
+    );
+  }
+
+  return stateDir;
+}

package/src/state/errors.ts

@@ -0,0 +1,97 @@
+/**
+ * Error classes for state management operations
+ *
+ * Provides typed errors with descriptive messages for state-related failures
+ */
+
+/**
+ * Base error class for state management errors
+ */
+export class StateError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StateError";
+  }
+}
+
+/**
+ * Error thrown when the state directory cannot be created
+ */
+export class StateDirectoryCreateError extends StateError {
+  /** Path that could not be created */
+  public readonly path: string;
+  /** System error code if available (e.g., EACCES, ENOENT) */
+  public readonly code?: string;
+
+  constructor(message: string, path: string, cause?: Error) {
+    super(message);
+    this.name = "StateDirectoryCreateError";
+    this.path = path;
+    this.cause = cause;
+    this.code = (cause as NodeJS.ErrnoException | undefined)?.code;
+  }
+}
+
+/**
+ * Error thrown when the state directory validation fails
+ */
+export class StateDirectoryValidationError extends StateError {
+  /** Paths that failed validation */
+  public readonly missingPaths: string[];
+
+  constructor(message: string, missingPaths: string[]) {
+    super(message);
+    this.name = "StateDirectoryValidationError";
+    this.missingPaths = missingPaths;
+  }
+}
+
+/**
+ * Error thrown when the state file cannot be read or written
+ */
+export class StateFileError extends StateError {
+  /** Path to the state file */
+  public readonly path: string;
+  /** The operation that failed */
+  public readonly operation: "read" | "write";
+
+  constructor(
+    message: string,
+    path: string,
+    operation: "read" | "write",
+    cause?: Error
+  ) {
+    super(message);
+    this.name = "StateFileError";
+    this.path = path;
+    this.operation = operation;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Get a descriptive error message for common permission errors
+ */
+export function getPermissionErrorMessage(
+  code: string | undefined,
+  path: string
+): string {
+  switch (code) {
+    case "EACCES":
+      return `Permission denied: Cannot access '${path}'. Check file permissions.`;
+    case "EPERM":
+      return `Operation not permitted: Cannot modify '${path}'. This may require elevated privileges.`;
+    case "EROFS":
+      return `Read-only filesystem: Cannot write to '${path}'.`;
+    case "ENOSPC":
+      return `No space left on device: Cannot create '${path}'.`;
+    case "ENOENT":
+      return `Path does not exist: '${path}' or one of its parent directories is missing.`;
+    case "ENOTDIR":
+      return `Not a directory: A component of '${path}' is not a directory.`;
+    case "EEXIST":
+      return `Path already exists: '${path}' already exists as a file but should be a directory.`;
+    default:
+      return `Failed to access '${path}'${code ? ` (${code})` : ""}.`;
+  }
+}

package/src/state/fleet-state.ts

@@ -0,0 +1,284 @@
+/**
+ * Fleet state management (state.yaml)
+ *
+ * Provides functions for reading, writing, and updating fleet state.
+ * Handles missing files gracefully and corrupted files with warnings.
+ */
+
+import { ZodError } from "zod";
+import {
+  FleetStateSchema,
+  createInitialFleetState,
+  type FleetState,
+  type AgentState,
+} from "./schemas/fleet-state.js";
+import { safeReadYaml } from "./utils/reads.js";
+import { atomicWriteYaml } from "./utils/atomic.js";
+import { StateFileError } from "./errors.js";
+
+/**
+ * Logger interface for warning messages
+ */
+export interface StateLogger {
+  warn: (message: string) => void;
+}
+
+/**
+ * Default console logger
+ */
+const defaultLogger: StateLogger = {
+  warn: (message: string) => console.warn(`[herdctl] ${message}`),
+};
+
+/**
+ * Options for reading fleet state
+ */
+export interface ReadFleetStateOptions {
+  /**
+   * Logger for warning messages (e.g., corrupted file warnings)
+   * Default: console.warn
+   */
+  logger?: StateLogger;
+}
+
+/**
+ * Options for writing fleet state
+ */
+export interface WriteFleetStateOptions {
+  /**
+   * YAML indent level
+   * Default: 2
+   */
+  indent?: number;
+}
+
+/**
+ * Read and validate fleet state from state.yaml
+ *
+ * Handles:
+ * - Missing file: Returns default empty state
+ * - Corrupted file: Logs warning, returns default empty state
+ * - Valid file: Returns validated FleetState
+ *
+ * @param stateFilePath - Path to state.yaml file
+ * @param options - Read options including logger
+ * @returns Validated FleetState object
+ *
+ * @example
+ * ```typescript
+ * const state = await readFleetState('.herdctl/state.yaml');
+ * console.log(state.fleet.started_at);
+ * console.log(state.agents);
+ * ```
+ */
+export async function readFleetState(
+  stateFilePath: string,
+  options: ReadFleetStateOptions = {}
+): Promise<FleetState> {
+  const logger = options.logger ?? defaultLogger;
+
+  // Attempt to read the file
+  const readResult = await safeReadYaml<unknown>(stateFilePath);
+
+  // Handle file not found - return default state
+  if (!readResult.success) {
+    if (readResult.error.code === "ENOENT") {
+      return createInitialFleetState();
+    }
+    // For other read errors, log and return default
+    logger.warn(
+      `Failed to read state file '${stateFilePath}': ${readResult.error.message}. Using default state.`
+    );
+    return createInitialFleetState();
+  }
+
+  // Handle empty file - return default state
+  if (readResult.data === null || readResult.data === undefined) {
+    return createInitialFleetState();
+  }
+
+  // Validate against schema
+  try {
+    return FleetStateSchema.parse(readResult.data);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const issues = error.issues
+        .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+        .join(", ");
+      logger.warn(
+        `Corrupted state file '${stateFilePath}': ${issues}. Using default state.`
+      );
+      return createInitialFleetState();
+    }
+    // Unexpected error - log and return default
+    logger.warn(
+      `Unexpected error parsing state file '${stateFilePath}': ${(error as Error).message}. Using default state.`
+    );
+    return createInitialFleetState();
+  }
+}
+
+/**
+ * Write fleet state to state.yaml atomically
+ *
+ * Uses atomic write (write to temp file, then rename) to prevent corruption.
+ *
+ * @param stateFilePath - Path to state.yaml file
+ * @param state - FleetState object to write
+ * @param options - Write options
+ * @throws {StateFileError} If write fails
+ *
+ * @example
+ * ```typescript
+ * const state = await readFleetState('.herdctl/state.yaml');
+ * state.fleet.started_at = new Date().toISOString();
+ * await writeFleetState('.herdctl/state.yaml', state);
+ * ```
+ */
+export async function writeFleetState(
+  stateFilePath: string,
+  state: FleetState,
+  options: WriteFleetStateOptions = {}
+): Promise<void> {
+  // Validate before writing
+  const validatedState = FleetStateSchema.parse(state);
+
+  try {
+    await atomicWriteYaml(stateFilePath, validatedState, {
+      indent: options.indent ?? 2,
+    });
+  } catch (error) {
+    throw new StateFileError(
+      `Failed to write state file '${stateFilePath}': ${(error as Error).message}`,
+      stateFilePath,
+      "write",
+      error as Error
+    );
+  }
+}
+
+/**
+ * Partial updates for agent state
+ */
+export type AgentStateUpdates = Partial<AgentState>;
+
+/**
+ * Update a single agent's state within the fleet state
+ *
+ * This is a convenience function that:
+ * 1. Reads current state
+ * 2. Applies partial updates to the specified agent
+ * 3. Writes the updated state back atomically
+ *
+ * If the agent doesn't exist, it will be created with the provided updates.
+ *
+ * @param stateFilePath - Path to state.yaml file
+ * @param agentName - Name of the agent to update
+ * @param updates - Partial AgentState updates to apply
+ * @param options - Options for read/write operations
+ * @returns The updated FleetState
+ * @throws {StateFileError} If write fails
+ *
+ * @example
+ * ```typescript
+ * // Mark agent as running with a job
+ * await updateAgentState('.herdctl/state.yaml', 'my-agent', {
+ *   status: 'running',
+ *   current_job: 'job-123',
+ * });
+ *
+ * // Clear error state
+ * await updateAgentState('.herdctl/state.yaml', 'my-agent', {
+ *   status: 'idle',
+ *   error_message: null,
+ * });
+ * ```
+ */
+export async function updateAgentState(
+  stateFilePath: string,
+  agentName: string,
+  updates: AgentStateUpdates,
+  options: ReadFleetStateOptions & WriteFleetStateOptions = {}
+): Promise<FleetState> {
+  // Read current state
+  const currentState = await readFleetState(stateFilePath, options);
+
+  // Get current agent state or create new one
+  const currentAgentState = currentState.agents[agentName] ?? { status: "idle" };
+
+  // Merge updates
+  const updatedAgentState: AgentState = {
+    ...currentAgentState,
+    ...updates,
+  };
+
+  // Update the state
+  const updatedState: FleetState = {
+    ...currentState,
+    agents: {
+      ...currentState.agents,
+      [agentName]: updatedAgentState,
+    },
+  };
+
+  // Write back
+  await writeFleetState(stateFilePath, updatedState, options);
+
+  return updatedState;
+}
+
+/**
+ * Initialize fleet state with started_at timestamp if not already set
+ *
+ * @param stateFilePath - Path to state.yaml file
+ * @param options - Options for read/write operations
+ * @returns The initialized FleetState
+ */
+export async function initializeFleetState(
+  stateFilePath: string,
+  options: ReadFleetStateOptions & WriteFleetStateOptions = {}
+): Promise<FleetState> {
+  const currentState = await readFleetState(stateFilePath, options);
+
+  // Only set started_at if not already set
+  if (!currentState.fleet.started_at) {
+    const updatedState: FleetState = {
+      ...currentState,
+      fleet: {
+        ...currentState.fleet,
+        started_at: new Date().toISOString(),
+      },
+    };
+    await writeFleetState(stateFilePath, updatedState, options);
+    return updatedState;
+  }
+
+  return currentState;
+}
+
+/**
+ * Remove an agent from the fleet state
+ *
+ * @param stateFilePath - Path to state.yaml file
+ * @param agentName - Name of the agent to remove
+ * @param options - Options for read/write operations
+ * @returns The updated FleetState
+ */
+export async function removeAgentState(
+  stateFilePath: string,
+  agentName: string,
+  options: ReadFleetStateOptions & WriteFleetStateOptions = {}
+): Promise<FleetState> {
+  const currentState = await readFleetState(stateFilePath, options);
+
+  // Create new agents map without the specified agent
+  const { [agentName]: _, ...remainingAgents } = currentState.agents;
+
+  const updatedState: FleetState = {
+    ...currentState,
+    agents: remainingAgents,
+  };
+
+  await writeFleetState(stateFilePath, updatedState, options);
+  return updatedState;
+}

package/src/state/index.ts

@@ -0,0 +1,79 @@
+/**
+ * State management module
+ *
+ * Provides utilities for managing herdctl state files including:
+ * - State directory initialization and management
+ * - Atomic file writes to prevent corruption
+ * - YAML and JSONL file operations
+ * - Safe reads with validation
+ * - Fleet state (state.yaml) management
+ * - Job metadata (job-<id>.yaml) management
+ */
+
+// Re-export types
+export * from "./types.js";
+
+// Re-export errors
+export * from "./errors.js";
+
+// Re-export schemas
+export * from "./schemas/index.js";
+
+// Re-export directory functions
+export {
+  initStateDirectory,
+  getStateDirectory,
+  validateStateDirectory,
+} from "./directory.js";
+
+// Re-export file utilities
+export * from "./utils/index.js";
+
+// Re-export fleet state functions
+export {
+  readFleetState,
+  writeFleetState,
+  updateAgentState,
+  initializeFleetState,
+  removeAgentState,
+  type StateLogger,
+  type ReadFleetStateOptions,
+  type WriteFleetStateOptions,
+  type AgentStateUpdates,
+} from "./fleet-state.js";
+
+// Re-export job metadata functions
+export {
+  createJob,
+  updateJob,
+  getJob,
+  listJobs,
+  deleteJob,
+  type JobMetadataOptions,
+  type JobLogger,
+  type JobMetadataUpdates,
+  type ListJobsFilter,
+  type ListJobsResult,
+} from "./job-metadata.js";
+
+// Re-export job output functions
+export {
+  getJobOutputPath,
+  appendJobOutput,
+  appendJobOutputBatch,
+  readJobOutput,
+  readJobOutputAll,
+  type JobOutputLogger,
+  type JobOutputOptions,
+  type ReadJobOutputOptions,
+} from "./job-output.js";
+
+// Re-export session functions
+export {
+  getSessionInfo,
+  updateSessionInfo,
+  clearSession,
+  type SessionOptions,
+  type SessionLogger,
+  type SessionInfoUpdates,
+} from "./session.js";