@herdctl/core 0.0.1 → 0.1.0

package/src/state/directory.ts

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

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

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

@@ -1,79 +0,0 @@
-/**
- * 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";