@herdctl/core 5.5.0 → 5.7.0

package/dist/distribution/agent-remover.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Agent Remover for herdctl
+ *
+ * Handles the filesystem and config operations for removing an installed agent.
+ * This includes:
+ * - Deleting the agent directory (optionally preserving workspace)
+ * - Removing the agent reference from herdctl.yaml
+ * - Scanning for env variables to report back to the user
+ */
+import { FleetManagerError, type FleetManagerErrorCode } from "../fleet-manager/errors.js";
+import { type EnvScanResult } from "./env-scanner.js";
+/**
+ * Options for removing an agent
+ */
+export interface RemoveOptions {
+    /** Agent name to remove */
+    name: string;
+    /** Path to herdctl.yaml */
+    configPath: string;
+    /** Base directory of the project (defaults to dirname of configPath) */
+    baseDir?: string;
+    /** If true, preserve workspace/ directory contents */
+    keepWorkspace?: boolean;
+}
+/**
+ * Result of removing an agent
+ */
+export interface RemoveResult {
+    /** The agent name that was removed */
+    agentName: string;
+    /** The path that was removed */
+    removedPath: string;
+    /** Whether files were actually deleted */
+    filesRemoved: boolean;
+    /** Whether the fleet config was updated */
+    configUpdated: boolean;
+    /** Environment variables that were used by this agent (for user reference) */
+    envVariables?: EnvScanResult;
+    /** Whether workspace was preserved */
+    workspacePreserved: boolean;
+}
+/** Error code: Agent not found in fleet config */
+export declare const AGENT_NOT_FOUND: FleetManagerErrorCode;
+/**
+ * Error thrown when agent removal fails
+ */
+export declare class AgentRemoveError extends FleetManagerError {
+    constructor(message: string, code: FleetManagerErrorCode);
+}
+/**
+ * Remove an agent from the fleet
+ *
+ * This function:
+ * 1. Uses discoverAgents() to find the agent by name
+ * 2. Scans agent.yaml for env variables (before deleting!) to report them
+ * 3. Deletes the agent directory (optionally preserving workspace/)
+ * 4. Removes the agent reference from herdctl.yaml
+ *
+ * @param options - Remove options including agent name and config path
+ * @returns Result indicating what was removed
+ * @throws {AgentRemoveError} When the agent is not found
+ *
+ * @example
+ * ```typescript
+ * const result = await removeAgent({
+ *   name: "my-agent",
+ *   configPath: "/path/to/herdctl.yaml"
+ * });
+ *
+ * if (result.filesRemoved) {
+ *   console.log(`Deleted: ${result.removedPath}`);
+ * }
+ *
+ * if (result.envVariables?.variables.length > 0) {
+ *   console.log("You may want to clean up these env vars:");
+ *   for (const v of result.envVariables.variables) {
+ *     console.log(`  ${v.name}`);
+ *   }
+ * }
+ * ```
+ */
+export declare function removeAgent(options: RemoveOptions): Promise<RemoveResult>;
+//# sourceMappingURL=agent-remover.d.ts.map

package/dist/distribution/agent-remover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-remover.d.ts","sourceRoot":"","sources":["../../src/distribution/agent-remover.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAG3F,OAAO,EAAE,KAAK,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AASxE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,YAAY,EAAE,OAAO,CAAC;IACtB,2CAA2C;IAC3C,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,sCAAsC;IACtC,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAMD,kDAAkD;AAClD,eAAO,MAAM,eAAe,EAAE,qBAAyC,CAAC;AAExE;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB;gBACzC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB;CAIzD;AAiFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA6G/E"}

package/dist/distribution/agent-remover.js

@@ -0,0 +1,222 @@
+/**
+ * Agent Remover for herdctl
+ *
+ * Handles the filesystem and config operations for removing an installed agent.
+ * This includes:
+ * - Deleting the agent directory (optionally preserving workspace)
+ * - Removing the agent reference from herdctl.yaml
+ * - Scanning for env variables to report back to the user
+ */
+import * as fs from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { FleetManagerError } from "../fleet-manager/errors.js";
+import { createLogger } from "../utils/logger.js";
+import { discoverAgents } from "./agent-discovery.js";
+import { scanEnvVariables } from "./env-scanner.js";
+import { FleetConfigError, removeAgentFromFleetConfig } from "./fleet-config-updater.js";
+const logger = createLogger("distribution:remover");
+// =============================================================================
+// Error Classes
+// =============================================================================
+/** Error code: Agent not found in fleet config */
+export const AGENT_NOT_FOUND = "AGENT_NOT_FOUND";
+/**
+ * Error thrown when agent removal fails
+ */
+export class AgentRemoveError extends FleetManagerError {
+    constructor(message, code) {
+        super(message, { code });
+        this.name = "AgentRemoveError";
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Check if a path exists
+ */
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Safely read a file's contents
+ */
+async function readFileContent(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete a directory and all its contents, optionally preserving the workspace subdirectory
+ */
+async function deleteAgentDirectory(agentDir, keepWorkspace) {
+    // Check if directory exists
+    if (!(await pathExists(agentDir))) {
+        logger.debug("Agent directory does not exist, nothing to delete", { path: agentDir });
+        return { deleted: false, workspacePreserved: false };
+    }
+    const workspacePath = join(agentDir, "workspace");
+    const hasWorkspace = await pathExists(workspacePath);
+    if (keepWorkspace && hasWorkspace) {
+        // Delete everything except workspace/
+        logger.debug("Preserving workspace, deleting other files", { path: agentDir });
+        const entries = await fs.readdir(agentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name === "workspace") {
+                continue;
+            }
+            const entryPath = join(agentDir, entry.name);
+            await fs.rm(entryPath, { recursive: true, force: true });
+            logger.debug("Deleted entry", { path: entryPath });
+        }
+        return { deleted: true, workspacePreserved: true };
+    }
+    else {
+        // Delete the entire directory
+        logger.debug("Deleting entire agent directory", { path: agentDir });
+        await fs.rm(agentDir, { recursive: true, force: true });
+        return { deleted: true, workspacePreserved: false };
+    }
+}
+/**
+ * Find an agent by name in the discovery result
+ */
+function findAgentByName(agents, name) {
+    return agents.find((agent) => agent.name === name);
+}
+// =============================================================================
+// Main Function
+// =============================================================================
+/**
+ * Remove an agent from the fleet
+ *
+ * This function:
+ * 1. Uses discoverAgents() to find the agent by name
+ * 2. Scans agent.yaml for env variables (before deleting!) to report them
+ * 3. Deletes the agent directory (optionally preserving workspace/)
+ * 4. Removes the agent reference from herdctl.yaml
+ *
+ * @param options - Remove options including agent name and config path
+ * @returns Result indicating what was removed
+ * @throws {AgentRemoveError} When the agent is not found
+ *
+ * @example
+ * ```typescript
+ * const result = await removeAgent({
+ *   name: "my-agent",
+ *   configPath: "/path/to/herdctl.yaml"
+ * });
+ *
+ * if (result.filesRemoved) {
+ *   console.log(`Deleted: ${result.removedPath}`);
+ * }
+ *
+ * if (result.envVariables?.variables.length > 0) {
+ *   console.log("You may want to clean up these env vars:");
+ *   for (const v of result.envVariables.variables) {
+ *     console.log(`  ${v.name}`);
+ *   }
+ * }
+ * ```
+ */
+export async function removeAgent(options) {
+    const { name, configPath, keepWorkspace = false } = options;
+    const baseDir = options.baseDir ?? dirname(configPath);
+    logger.info("Removing agent", { name, configPath, keepWorkspace });
+    // ==========================================================================
+    // Step 1: Discover agents to find the one we want to remove
+    // ==========================================================================
+    const discoveryResult = await discoverAgents({ configPath, baseDir });
+    const agent = findAgentByName(discoveryResult.agents, name);
+    if (!agent) {
+        throw new AgentRemoveError(`Agent '${name}' not found in fleet configuration. Run 'herdctl agent list' to see available agents.`, AGENT_NOT_FOUND);
+    }
+    logger.debug("Found agent to remove", {
+        name: agent.name,
+        path: agent.path,
+        configPath: agent.configPath,
+    });
+    // ==========================================================================
+    // Step 2: Scan for env variables BEFORE deleting (for user reference)
+    // ==========================================================================
+    let envVariables;
+    const agentYamlPath = join(agent.path, "agent.yaml");
+    const agentYamlContent = await readFileContent(agentYamlPath);
+    if (agentYamlContent) {
+        envVariables = scanEnvVariables(agentYamlContent);
+        logger.debug("Scanned env variables", {
+            total: envVariables.variables.length,
+            required: envVariables.required.length,
+            optional: envVariables.optional.length,
+        });
+    }
+    // ==========================================================================
+    // Step 3: Delete the agent directory
+    // ==========================================================================
+    const { deleted: filesRemoved, workspacePreserved } = await deleteAgentDirectory(agent.path, keepWorkspace);
+    logger.debug("Directory deletion result", {
+        filesRemoved,
+        workspacePreserved,
+        path: agent.path,
+    });
+    // ==========================================================================
+    // Step 4: Remove the agent reference from herdctl.yaml
+    // ==========================================================================
+    let configUpdated = false;
+    try {
+        const configResult = await removeAgentFromFleetConfig({
+            configPath,
+            agentPath: agent.configPath,
+        });
+        configUpdated = configResult.modified;
+        if (configResult.modified) {
+            logger.info("Removed agent from fleet config", { agentPath: agent.configPath });
+        }
+        else if (!configResult.alreadyExists) {
+            logger.debug("Agent was not in fleet config", { agentPath: agent.configPath });
+        }
+    }
+    catch (error) {
+        // Config update failure shouldn't fail the overall operation
+        // (files are already deleted at this point)
+        if (error instanceof FleetConfigError) {
+            logger.warn("Failed to update fleet config, but files were removed", {
+                error: error.message,
+                code: error.code,
+            });
+        }
+        else {
+            logger.warn("Unexpected error updating fleet config", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    // ==========================================================================
+    // Return result
+    // ==========================================================================
+    const result = {
+        agentName: agent.name,
+        removedPath: agent.path,
+        filesRemoved,
+        configUpdated,
+        envVariables,
+        workspacePreserved,
+    };
+    logger.info("Agent removal complete", {
+        agentName: result.agentName,
+        filesRemoved: result.filesRemoved,
+        configUpdated: result.configUpdated,
+        workspacePreserved: result.workspacePreserved,
+    });
+    return result;
+}
+//# sourceMappingURL=agent-remover.js.map

package/dist/distribution/agent-remover.js.map

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

package/dist/distribution/agent-repo-metadata.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Agent Repository Metadata Schema (`herdctl.json`)
+ *
+ * Validates the metadata file that agent authors include in their repositories
+ * to describe their agent for registry listing and installation validation.
+ *
+ * This file is found at the root of an agent repository and provides:
+ * - Basic info: name, version, description, author
+ * - Source info: repository, homepage, license
+ * - Discovery: keywords, category, tags
+ * - Requirements: herdctl version, runtime, env vars, workspace, docker
+ * - Presentation: screenshots, examples
+ */
+import { z } from "zod";
+import { AGENT_NAME_PATTERN } from "../config/schema.js";
+/**
+ * Requirements schema for agent dependencies and constraints.
+ *
+ * Specifies what the agent needs to run properly:
+ * - herdctl version compatibility
+ * - Runtime backend (cli, sdk)
+ * - Required environment variables
+ * - Workspace requirement
+ * - Docker requirement
+ */
+export declare const AgentRequiresSchema: z.ZodObject<{
+    /** Minimum herdctl version required (semver range, e.g., ">=0.1.0") */
+    herdctl: z.ZodOptional<z.ZodString>;
+    /** Runtime backend required (e.g., "cli" for Claude CLI) */
+    runtime: z.ZodOptional<z.ZodString>;
+    /** Required environment variable names (user must set these) */
+    env: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Whether the agent requires a workspace directory */
+    workspace: z.ZodOptional<z.ZodBoolean>;
+    /** Whether the agent requires Docker */
+    docker: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    env?: string[] | undefined;
+    docker?: boolean | undefined;
+    runtime?: string | undefined;
+    workspace?: boolean | undefined;
+    herdctl?: string | undefined;
+}, {
+    env?: string[] | undefined;
+    docker?: boolean | undefined;
+    runtime?: string | undefined;
+    workspace?: boolean | undefined;
+    herdctl?: string | undefined;
+}>;
+export type AgentRequires = z.infer<typeof AgentRequiresSchema>;
+/**
+ * Schema for `herdctl.json` metadata files in agent repositories.
+ *
+ * This metadata is used for:
+ * - Registry listing and search
+ * - Installation validation
+ * - Displaying agent information
+ *
+ * @example
+ * ```json
+ * {
+ *   "$schema": "https://herdctl.dev/schemas/agent-metadata.json",
+ *   "name": "website-monitor",
+ *   "version": "1.0.0",
+ *   "description": "Monitor website uptime and send Discord alerts",
+ *   "author": "herdctl-examples",
+ *   "repository": "github:herdctl-examples/website-monitor-agent",
+ *   "license": "MIT",
+ *   "keywords": ["monitoring", "uptime", "alerts"],
+ *   "requires": {
+ *     "herdctl": ">=0.1.0",
+ *     "runtime": "cli",
+ *     "env": ["WEBSITES", "DISCORD_WEBHOOK_URL"],
+ *     "workspace": true
+ *   },
+ *   "category": "operations",
+ *   "tags": ["monitoring", "automation"]
+ * }
+ * ```
+ */
+export declare const AgentRepoMetadataSchema: z.ZodObject<{
+    /** JSON schema URL for IDE validation (optional) */
+    $schema: z.ZodOptional<z.ZodString>;
+    /**
+     * Agent name - must match AGENT_NAME_PATTERN.
+     * This should match the `name` field in the agent's `agent.yaml`.
+     */
+    name: z.ZodString;
+    /** Agent version (semver format, e.g., "1.0.0") */
+    version: z.ZodString;
+    /** Human-readable description of what the agent does */
+    description: z.ZodString;
+    /** Author name or organization */
+    author: z.ZodString;
+    /** Source repository specifier (e.g., "github:user/repo") */
+    repository: z.ZodOptional<z.ZodString>;
+    /** Homepage URL */
+    homepage: z.ZodOptional<z.ZodString>;
+    /** SPDX license identifier (e.g., "MIT", "Apache-2.0") */
+    license: z.ZodOptional<z.ZodString>;
+    /** Keywords for search and discovery */
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Requirements and dependencies */
+    requires: z.ZodOptional<z.ZodObject<{
+        /** Minimum herdctl version required (semver range, e.g., ">=0.1.0") */
+        herdctl: z.ZodOptional<z.ZodString>;
+        /** Runtime backend required (e.g., "cli" for Claude CLI) */
+        runtime: z.ZodOptional<z.ZodString>;
+        /** Required environment variable names (user must set these) */
+        env: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** Whether the agent requires a workspace directory */
+        workspace: z.ZodOptional<z.ZodBoolean>;
+        /** Whether the agent requires Docker */
+        docker: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        env?: string[] | undefined;
+        docker?: boolean | undefined;
+        runtime?: string | undefined;
+        workspace?: boolean | undefined;
+        herdctl?: string | undefined;
+    }, {
+        env?: string[] | undefined;
+        docker?: boolean | undefined;
+        runtime?: string | undefined;
+        workspace?: boolean | undefined;
+        herdctl?: string | undefined;
+    }>>;
+    /** Agent category for browsing (e.g., "operations", "development", "data") */
+    category: z.ZodOptional<z.ZodString>;
+    /** Tags for filtering (similar to keywords but for categorization) */
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** URLs to screenshot images for showcase */
+    screenshots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Example use cases as name-description pairs */
+    examples: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    $schema?: string | undefined;
+    repository?: string | undefined;
+    homepage?: string | undefined;
+    license?: string | undefined;
+    keywords?: string[] | undefined;
+    requires?: {
+        env?: string[] | undefined;
+        docker?: boolean | undefined;
+        runtime?: string | undefined;
+        workspace?: boolean | undefined;
+        herdctl?: string | undefined;
+    } | undefined;
+    category?: string | undefined;
+    tags?: string[] | undefined;
+    screenshots?: string[] | undefined;
+    examples?: Record<string, string> | undefined;
+}, {
+    name: string;
+    description: string;
+    version: string;
+    author: string;
+    $schema?: string | undefined;
+    repository?: string | undefined;
+    homepage?: string | undefined;
+    license?: string | undefined;
+    keywords?: string[] | undefined;
+    requires?: {
+        env?: string[] | undefined;
+        docker?: boolean | undefined;
+        runtime?: string | undefined;
+        workspace?: boolean | undefined;
+        herdctl?: string | undefined;
+    } | undefined;
+    category?: string | undefined;
+    tags?: string[] | undefined;
+    screenshots?: string[] | undefined;
+    examples?: Record<string, string> | undefined;
+}>;
+export type AgentRepoMetadata = z.infer<typeof AgentRepoMetadataSchema>;
+export { AGENT_NAME_PATTERN };
+//# sourceMappingURL=agent-repo-metadata.d.ts.map

package/dist/distribution/agent-repo-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-repo-metadata.d.ts","sourceRoot":"","sources":["../../src/distribution/agent-repo-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AA4BzD;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;IAE5B,uEAAuE;;IAQvE,4DAA4D;;IAG5D,gEAAgE;;IAGhE,uDAAuD;;IAGvD,wCAAwC;;;;;;;;;;;;;;EAGjC,CAAC;AAEZ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,uBAAuB;IAEhC,oDAAoD;;IAGpD;;;OAGG;;IAMH,mDAAmD;;IAKnD,wDAAwD;;IAGxD,kCAAkC;;IAGlC,6DAA6D;;IAG7D,mBAAmB;;IAGnB,0DAA0D;;IAG1D,wCAAwC;;IAGxC,oCAAoC;;QA/FpC,uEAAuE;;QAQvE,4DAA4D;;QAG5D,gEAAgE;;QAGhE,uDAAuD;;QAGvD,wCAAwC;;;;;;;;;;;;;;;IAiFxC,8EAA8E;;IAG9E,sEAAsE;;IAGtE,6CAA6C;;IAK7C,kDAAkD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAG3C,CAAC;AAEZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAMxE,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/distribution/agent-repo-metadata.js

@@ -0,0 +1,143 @@
+/**
+ * Agent Repository Metadata Schema (`herdctl.json`)
+ *
+ * Validates the metadata file that agent authors include in their repositories
+ * to describe their agent for registry listing and installation validation.
+ *
+ * This file is found at the root of an agent repository and provides:
+ * - Basic info: name, version, description, author
+ * - Source info: repository, homepage, license
+ * - Discovery: keywords, category, tags
+ * - Requirements: herdctl version, runtime, env vars, workspace, docker
+ * - Presentation: screenshots, examples
+ */
+import { z } from "zod";
+import { AGENT_NAME_PATTERN } from "../config/schema.js";
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Semver pattern for version validation.
+ * Matches versions like "1.0.0", "2.3.4-beta.1", "1.0.0+build.123"
+ */
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?(?:\+[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?$/;
+/**
+ * Semver range pattern for version constraints.
+ * Matches ranges like ">=1.0.0", "^2.0.0", "~1.2.3", "1.x", "*", ">=1.0.0 <2.0.0"
+ *
+ * This is a permissive pattern that accepts common semver range formats.
+ * Full semver range validation is complex; this pattern catches obvious errors
+ * while allowing valid npm-style version ranges.
+ */
+const SEMVER_RANGE_PATTERN = /^(?:[~^<>=]*\d+(?:\.\d+(?:\.\d+)?)?(?:-[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?(?:\s+[<>=]+\d+(?:\.\d+(?:\.\d+)?)?(?:-[\da-zA-Z-]+(?:\.[\da-zA-Z-]+)*)?)*|\d+(?:\.\d+)?\.x(?:\.x)?|\*)$/;
+// =============================================================================
+// Requirements Schema
+// =============================================================================
+/**
+ * Requirements schema for agent dependencies and constraints.
+ *
+ * Specifies what the agent needs to run properly:
+ * - herdctl version compatibility
+ * - Runtime backend (cli, sdk)
+ * - Required environment variables
+ * - Workspace requirement
+ * - Docker requirement
+ */
+export const AgentRequiresSchema = z
+    .object({
+    /** Minimum herdctl version required (semver range, e.g., ">=0.1.0") */
+    herdctl: z
+        .string()
+        .regex(SEMVER_RANGE_PATTERN, {
+        message: "herdctl version must be a valid semver range (e.g., '>=0.1.0', '^1.0.0')",
+    })
+        .optional(),
+    /** Runtime backend required (e.g., "cli" for Claude CLI) */
+    runtime: z.string().optional(),
+    /** Required environment variable names (user must set these) */
+    env: z.array(z.string()).optional(),
+    /** Whether the agent requires a workspace directory */
+    workspace: z.boolean().optional(),
+    /** Whether the agent requires Docker */
+    docker: z.boolean().optional(),
+})
+    .strict();
+// =============================================================================
+// Agent Repository Metadata Schema
+// =============================================================================
+/**
+ * Schema for `herdctl.json` metadata files in agent repositories.
+ *
+ * This metadata is used for:
+ * - Registry listing and search
+ * - Installation validation
+ * - Displaying agent information
+ *
+ * @example
+ * ```json
+ * {
+ *   "$schema": "https://herdctl.dev/schemas/agent-metadata.json",
+ *   "name": "website-monitor",
+ *   "version": "1.0.0",
+ *   "description": "Monitor website uptime and send Discord alerts",
+ *   "author": "herdctl-examples",
+ *   "repository": "github:herdctl-examples/website-monitor-agent",
+ *   "license": "MIT",
+ *   "keywords": ["monitoring", "uptime", "alerts"],
+ *   "requires": {
+ *     "herdctl": ">=0.1.0",
+ *     "runtime": "cli",
+ *     "env": ["WEBSITES", "DISCORD_WEBHOOK_URL"],
+ *     "workspace": true
+ *   },
+ *   "category": "operations",
+ *   "tags": ["monitoring", "automation"]
+ * }
+ * ```
+ */
+export const AgentRepoMetadataSchema = z
+    .object({
+    /** JSON schema URL for IDE validation (optional) */
+    $schema: z.string().optional(),
+    /**
+     * Agent name - must match AGENT_NAME_PATTERN.
+     * This should match the `name` field in the agent's `agent.yaml`.
+     */
+    name: z.string().regex(AGENT_NAME_PATTERN, {
+        message: "Agent name must start with a letter or number and contain only letters, numbers, underscores, and hyphens",
+    }),
+    /** Agent version (semver format, e.g., "1.0.0") */
+    version: z.string().regex(SEMVER_PATTERN, {
+        message: "Version must be a valid semver string (e.g., '1.0.0', '2.3.4-beta.1')",
+    }),
+    /** Human-readable description of what the agent does */
+    description: z.string().min(1, { message: "Description cannot be empty" }),
+    /** Author name or organization */
+    author: z.string().min(1, { message: "Author cannot be empty" }),
+    /** Source repository specifier (e.g., "github:user/repo") */
+    repository: z.string().optional(),
+    /** Homepage URL */
+    homepage: z.string().url({ message: "Homepage must be a valid URL" }).optional(),
+    /** SPDX license identifier (e.g., "MIT", "Apache-2.0") */
+    license: z.string().optional(),
+    /** Keywords for search and discovery */
+    keywords: z.array(z.string()).optional(),
+    /** Requirements and dependencies */
+    requires: AgentRequiresSchema.optional(),
+    /** Agent category for browsing (e.g., "operations", "development", "data") */
+    category: z.string().optional(),
+    /** Tags for filtering (similar to keywords but for categorization) */
+    tags: z.array(z.string()).optional(),
+    /** URLs to screenshot images for showcase */
+    screenshots: z
+        .array(z.string().url({ message: "Screenshot URLs must be valid URLs" }))
+        .optional(),
+    /** Example use cases as name-description pairs */
+    examples: z.record(z.string(), z.string()).optional(),
+})
+    .strict();
+// =============================================================================
+// Re-export AGENT_NAME_PATTERN for convenience
+// =============================================================================
+export { AGENT_NAME_PATTERN };
+//# sourceMappingURL=agent-repo-metadata.js.map

package/dist/distribution/agent-repo-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-repo-metadata.js","sourceRoot":"","sources":["../../src/distribution/agent-repo-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,cAAc,GAClB,4FAA4F,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,oBAAoB,GACxB,kLAAkL,CAAC;AAErL,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,uEAAuE;IACvE,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,KAAK,CAAC,oBAAoB,EAAE;QAC3B,OAAO,EAAE,0EAA0E;KACpF,CAAC;SACD,QAAQ,EAAE;IAEb,4DAA4D;IAC5D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE9B,gEAAgE;IAChE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAEnC,uDAAuD;IACvD,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAEjC,wCAAwC;IACxC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ,gFAAgF;AAChF,mCAAmC;AACnC,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC;KACrC,MAAM,CAAC;IACN,oDAAoD;IACpD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE9B;;;OAGG;IACH,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,EAAE;QACzC,OAAO,EACL,2GAA2G;KAC9G,CAAC;IAEF,mDAAmD;IACnD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,cAAc,EAAE;QACxC,OAAO,EAAE,uEAAuE;KACjF,CAAC;IAEF,wDAAwD;IACxD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAAC;IAE1E,kCAAkC;IAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC;IAEhE,6DAA6D;IAC7D,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAEjC,mBAAmB;IACnB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CAAC,QAAQ,EAAE;IAEhF,0DAA0D;IAC1D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE9B,wCAAwC;IACxC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAExC,oCAAoC;IACpC,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,EAAE;IAExC,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE/B,sEAAsE;IACtE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAEpC,6CAA6C;IAC7C,WAAW,EAAE,CAAC;SACX,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,oCAAoC,EAAE,CAAC,CAAC;SACxE,QAAQ,EAAE;IAEb,kDAAkD;IAClD,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CACtD,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ,gFAAgF;AAChF,+CAA+C;AAC/C,gFAAgF;AAEhF,OAAO,EAAE,kBAAkB,EAAE,CAAC"}