@herdctl/core 5.5.0 → 5.7.0

package/dist/distribution/installation-metadata.js

@@ -0,0 +1,100 @@
+/**
+ * Installation metadata schema for agent distribution
+ *
+ * Validates the `metadata.json` file that lives in each installed agent's
+ * directory root. This file tracks where an agent was installed from and when.
+ *
+ * The schema is intentionally extensible (no .strict()) to support future
+ * features like agentic initialization without breaking existing installs.
+ */
+import { z } from "zod";
+// =============================================================================
+// Source Type Schema
+// =============================================================================
+/**
+ * Source types for installed agents
+ *
+ * - `github`: Installed from a GitHub repository
+ * - `local`: Installed from a local filesystem path
+ */
+export const SourceTypeSchema = z.enum(["github", "local"]);
+// =============================================================================
+// Source Schema
+// =============================================================================
+/**
+ * Source information schema
+ *
+ * Tracks the origin of an installed agent. The `type` field is required,
+ * while other fields are optional and depend on the source type:
+ *
+ * - `url`: The original source URL or path (GitHub URL, local path)
+ * - `ref`: Git reference (tag, branch, commit SHA) for GitHub sources
+ * - `version`: Version from herdctl.json at install time
+ */
+export const InstallationSourceSchema = z
+    .object({
+    /** The type of source (github or local) */
+    type: SourceTypeSchema,
+    /** The original source URL or path */
+    url: z.string().optional(),
+    /** Git reference (tag, branch, commit) for version-controlled sources */
+    ref: z.string().optional(),
+    /** Version from herdctl.json at install time */
+    version: z.string().optional(),
+})
+    .passthrough();
+// =============================================================================
+// ISO 8601 Timestamp Schema
+// =============================================================================
+/**
+ * ISO 8601 timestamp pattern
+ *
+ * Matches formats like:
+ * - 2024-01-15T10:30:00Z
+ * - 2024-01-15T10:30:00.123Z
+ * - 2024-01-15T10:30:00+00:00
+ * - 2024-01-15T10:30:00-05:00
+ */
+const ISO8601_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+/**
+ * Schema for ISO 8601 formatted timestamps
+ */
+export const ISO8601TimestampSchema = z.string().regex(ISO8601_PATTERN, {
+    message: "Timestamp must be in ISO 8601 format (e.g., 2024-01-15T10:30:00Z or 2024-01-15T10:30:00+00:00)",
+});
+// =============================================================================
+// Installation Metadata Schema
+// =============================================================================
+/**
+ * Installation metadata schema
+ *
+ * This schema validates the `metadata.json` file that tracks installation
+ * information for each agent. It is intentionally extensible (uses default
+ * Zod behavior, not .strict()) to allow adding future fields like
+ * `initialization` without breaking existing installs.
+ *
+ * @example
+ * ```json
+ * {
+ *   "source": {
+ *     "type": "github",
+ *     "url": "https://github.com/user/agent-repo",
+ *     "ref": "v1.0.0",
+ *     "version": "1.0.0"
+ *   },
+ *   "installed_at": "2024-01-15T10:30:00Z",
+ *   "installed_by": "herdctl@0.5.0"
+ * }
+ * ```
+ */
+export const InstallationMetadataSchema = z
+    .object({
+    /** Source information - where the agent was installed from */
+    source: InstallationSourceSchema,
+    /** ISO 8601 timestamp of when the agent was installed */
+    installed_at: ISO8601TimestampSchema,
+    /** herdctl version that performed the installation (e.g., "herdctl@0.5.0") */
+    installed_by: z.string().optional(),
+})
+    .passthrough();
+//# sourceMappingURL=installation-metadata.js.map

package/dist/distribution/installation-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installation-metadata.js","sourceRoot":"","sources":["../../src/distribution/installation-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;AAK5D,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC;KACtC,MAAM,CAAC;IACN,2CAA2C;IAC3C,IAAI,EAAE,gBAAgB;IAEtB,sCAAsC;IACtC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE1B,yEAAyE;IACzE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAE1B,gDAAgD;IAChD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC;KACD,WAAW,EAAE,CAAC;AAKjB,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAG,sEAAsE,CAAC;AAE/F;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,eAAe,EAAE;IACtE,OAAO,EACL,gGAAgG;CACnG,CAAC,CAAC;AAEH,gFAAgF;AAChF,+BAA+B;AAC/B,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC;KACxC,MAAM,CAAC;IACN,8DAA8D;IAC9D,MAAM,EAAE,wBAAwB;IAEhC,yDAAyD;IACzD,YAAY,EAAE,sBAAsB;IAEpC,8EAA8E;IAC9E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACpC,CAAC;KACD,WAAW,EAAE,CAAC"}

package/dist/distribution/repository-fetcher.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Repository fetching for agent distribution
+ *
+ * Fetches agent repositories from various sources (GitHub, local paths) and
+ * provides them in a temporary directory for validation and installation.
+ */
+import { FleetManagerError } from "../fleet-manager/errors.js";
+/**
+ * GitHub source specifier
+ */
+export interface GitHubFetchSource {
+    type: "github";
+    owner: string;
+    repo: string;
+    ref?: string;
+}
+/**
+ * Local filesystem source specifier
+ */
+export interface LocalFetchSource {
+    type: "local";
+    path: string;
+}
+/**
+ * Union of all fetch source types
+ */
+export type FetchSource = GitHubFetchSource | LocalFetchSource;
+/**
+ * Result of fetching a repository
+ *
+ * Note: Named RepositoryFetchResult to avoid collision with work-sources FetchResult
+ */
+export interface RepositoryFetchResult {
+    /** Path to the fetched repository contents */
+    path: string;
+    /** Cleanup function to remove the temporary directory */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Base error for repository fetching failures
+ */
+export declare class RepositoryFetchError extends FleetManagerError {
+    readonly source: FetchSource;
+    constructor(message: string, source: FetchSource, cause?: Error);
+}
+/**
+ * Error when GitHub authentication fails during clone
+ *
+ * Note: Named GitHubCloneAuthError to avoid collision with work-sources GitHubAuthError
+ */
+export declare class GitHubCloneAuthError extends RepositoryFetchError {
+    constructor(source: GitHubFetchSource, cause?: Error);
+}
+/**
+ * Error when a GitHub repository is not found
+ */
+export declare class GitHubRepoNotFoundError extends RepositoryFetchError {
+    constructor(source: GitHubFetchSource, cause?: Error);
+}
+/**
+ * Error when a network operation fails
+ */
+export declare class NetworkError extends RepositoryFetchError {
+    constructor(source: FetchSource, cause?: Error);
+}
+/**
+ * Error when a local path doesn't exist or isn't a directory
+ */
+export declare class LocalPathError extends RepositoryFetchError {
+    constructor(source: LocalFetchSource, reason: string, cause?: Error);
+}
+/**
+ * Fetch a repository from a source specifier
+ *
+ * Clones or copies the repository to a temporary directory and returns
+ * the path along with a cleanup function.
+ *
+ * @param source - The source specifier (GitHub or local)
+ * @returns The path to the fetched repository and a cleanup function
+ * @throws {GitHubCloneAuthError} When GitHub authentication fails
+ * @throws {GitHubRepoNotFoundError} When the GitHub repository doesn't exist
+ * @throws {NetworkError} When a network operation fails
+ * @throws {LocalPathError} When the local path is invalid
+ *
+ * @example
+ * ```typescript
+ * const result = await fetchRepository({
+ *   type: 'github',
+ *   owner: 'herdctl',
+ *   repo: 'example-agent',
+ *   ref: 'v1.0.0'
+ * });
+ *
+ * try {
+ *   // Use result.path to access the repository files
+ *   const agentYaml = await readFile(join(result.path, 'agent.yaml'));
+ * } finally {
+ *   // Always clean up when done
+ *   await result.cleanup();
+ * }
+ * ```
+ */
+export declare function fetchRepository(source: FetchSource): Promise<RepositoryFetchResult>;
+//# sourceMappingURL=repository-fetcher.d.ts.map

package/dist/distribution/repository-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-fetcher.d.ts","sourceRoot":"","sources":["../../src/distribution/repository-fetcher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAU/D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAMD;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,iBAAiB;aAGvC,MAAM,EAAE,WAAW;gBADnC,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,WAAW,EACnC,KAAK,CAAC,EAAE,KAAK;CAKhB;AAED;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,oBAAoB;gBAChD,MAAM,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,KAAK;CAUrD;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,oBAAoB;gBACnD,MAAM,EAAE,iBAAiB,EAAE,KAAK,CAAC,EAAE,KAAK;CASrD;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,oBAAoB;gBACxC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,KAAK;CAW/C;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,oBAAoB;gBAC1C,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAIpE;AAgKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAczF"}

package/dist/distribution/repository-fetcher.js

@@ -0,0 +1,246 @@
+/**
+ * Repository fetching for agent distribution
+ *
+ * Fetches agent repositories from various sources (GitHub, local paths) and
+ * provides them in a temporary directory for validation and installation.
+ */
+import { execFile } from "node:child_process";
+import { cp, mkdtemp, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { FleetManagerError } from "../fleet-manager/errors.js";
+import { createLogger } from "../utils/logger.js";
+const execFileAsync = promisify(execFile);
+const logger = createLogger("distribution");
+// =============================================================================
+// Error Classes
+// =============================================================================
+/**
+ * Base error for repository fetching failures
+ */
+export class RepositoryFetchError extends FleetManagerError {
+    source;
+    constructor(message, source, cause) {
+        super(message, { cause, code: "REPOSITORY_FETCH_ERROR" });
+        this.source = source;
+        this.name = "RepositoryFetchError";
+    }
+}
+/**
+ * Error when GitHub authentication fails during clone
+ *
+ * Note: Named GitHubCloneAuthError to avoid collision with work-sources GitHubAuthError
+ */
+export class GitHubCloneAuthError extends RepositoryFetchError {
+    constructor(source, cause) {
+        super(`Authentication failed for github:${source.owner}/${source.repo}. ` +
+            `Make sure your Git credentials are configured correctly. ` +
+            `For private repos, set up a GitHub personal access token or SSH key.`, source, cause);
+        this.name = "GitHubCloneAuthError";
+    }
+}
+/**
+ * Error when a GitHub repository is not found
+ */
+export class GitHubRepoNotFoundError extends RepositoryFetchError {
+    constructor(source, cause) {
+        super(`Repository not found: github:${source.owner}/${source.repo}. ` +
+            `Check that the owner and repository name are correct, and that you have access to the repo.`, source, cause);
+        this.name = "GitHubRepoNotFoundError";
+    }
+}
+/**
+ * Error when a network operation fails
+ */
+export class NetworkError extends RepositoryFetchError {
+    constructor(source, cause) {
+        const sourceStr = source.type === "github" ? `github:${source.owner}/${source.repo}` : source.type;
+        super(`Network error while fetching ${sourceStr}. ` +
+            `Check your internet connection and try again.`, source, cause);
+        this.name = "NetworkError";
+    }
+}
+/**
+ * Error when a local path doesn't exist or isn't a directory
+ */
+export class LocalPathError extends RepositoryFetchError {
+    constructor(source, reason, cause) {
+        super(`Local source error for "${source.path}": ${reason}`, source, cause);
+        this.name = "LocalPathError";
+    }
+}
+// =============================================================================
+// Implementation
+// =============================================================================
+/**
+ * Create a temporary directory for fetching
+ */
+async function createTempDir(prefix) {
+    const base = join(tmpdir(), `herdctl-${prefix}-`);
+    return mkdtemp(base);
+}
+/**
+ * Fetch a repository from GitHub via shallow clone
+ */
+async function fetchFromGitHub(source) {
+    const url = `https://github.com/${source.owner}/${source.repo}.git`;
+    const tempDir = await createTempDir("github");
+    logger.debug("Cloning GitHub repository", {
+        owner: source.owner,
+        repo: source.repo,
+        ref: source.ref,
+        tempDir,
+    });
+    const args = ["clone", "--depth", "1"];
+    if (source.ref) {
+        args.push("--branch", source.ref);
+    }
+    args.push(url, tempDir);
+    try {
+        await execFileAsync("git", args, {
+            env: {
+                ...process.env,
+                // Prevent interactive auth prompts from hanging
+                GIT_TERMINAL_PROMPT: "0",
+            },
+            timeout: 120000, // 2 minute timeout
+        });
+        logger.info("Successfully cloned repository", {
+            source: `github:${source.owner}/${source.repo}`,
+            ref: source.ref,
+        });
+        return {
+            path: tempDir,
+            cleanup: async () => {
+                logger.debug("Cleaning up temporary directory", { path: tempDir });
+                await rm(tempDir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (err) {
+        // Clean up temp dir on failure
+        await rm(tempDir, { recursive: true, force: true }).catch(() => {
+            /* ignore cleanup errors */
+        });
+        const error = err;
+        const stderr = error.stderr?.toLowerCase() ?? "";
+        // Node.js execFile returns exit code as number, but handle string for safety
+        const exitCode = typeof error.code === "number" ? error.code : parseInt(String(error.code), 10);
+        // Check specific error patterns FIRST before falling back to generic exit code checks.
+        // Git exit code 128 is used for multiple failure modes (auth, not found, etc.),
+        // so we must check message content to distinguish between them.
+        // Check for repository not found errors (specific patterns first)
+        if (stderr.includes("repository not found") ||
+            stderr.includes("does not exist") ||
+            stderr.includes("not found")) {
+            throw new GitHubRepoNotFoundError(source, error);
+        }
+        // Check for network errors
+        if (stderr.includes("could not resolve host") ||
+            stderr.includes("network") ||
+            stderr.includes("connection")) {
+            throw new NetworkError(source, error);
+        }
+        // Check for authentication errors - either explicit auth messages or
+        // exit code 128 with credential-related messages
+        if (stderr.includes("authentication") ||
+            stderr.includes("could not read") ||
+            exitCode === 128) {
+            throw new GitHubCloneAuthError(source, error);
+        }
+        // Generic error
+        throw new RepositoryFetchError(`Failed to clone github:${source.owner}/${source.repo}: ${error.message}`, source, error);
+    }
+}
+/**
+ * Fetch from a local filesystem path by copying to a temp directory
+ */
+async function fetchFromLocal(source) {
+    logger.debug("Copying local directory", { path: source.path });
+    // Validate the source path exists
+    let stats;
+    try {
+        stats = await stat(source.path);
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === "ENOENT") {
+            throw new LocalPathError(source, "Path does not exist");
+        }
+        throw new LocalPathError(source, `Cannot access path: ${error.message}`, error);
+    }
+    // Validate it's a directory
+    if (!stats.isDirectory()) {
+        throw new LocalPathError(source, "Path is not a directory");
+    }
+    // Copy to temp directory
+    const tempDir = await createTempDir("local");
+    try {
+        await cp(source.path, tempDir, { recursive: true });
+        logger.info("Successfully copied local directory", {
+            source: source.path,
+            dest: tempDir,
+        });
+        return {
+            path: tempDir,
+            cleanup: async () => {
+                logger.debug("Cleaning up temporary directory", { path: tempDir });
+                await rm(tempDir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (err) {
+        // Clean up temp dir on failure
+        await rm(tempDir, { recursive: true, force: true }).catch(() => {
+            /* ignore cleanup errors */
+        });
+        const error = err;
+        throw new LocalPathError(source, `Failed to copy directory: ${error.message}`, error);
+    }
+}
+/**
+ * Fetch a repository from a source specifier
+ *
+ * Clones or copies the repository to a temporary directory and returns
+ * the path along with a cleanup function.
+ *
+ * @param source - The source specifier (GitHub or local)
+ * @returns The path to the fetched repository and a cleanup function
+ * @throws {GitHubCloneAuthError} When GitHub authentication fails
+ * @throws {GitHubRepoNotFoundError} When the GitHub repository doesn't exist
+ * @throws {NetworkError} When a network operation fails
+ * @throws {LocalPathError} When the local path is invalid
+ *
+ * @example
+ * ```typescript
+ * const result = await fetchRepository({
+ *   type: 'github',
+ *   owner: 'herdctl',
+ *   repo: 'example-agent',
+ *   ref: 'v1.0.0'
+ * });
+ *
+ * try {
+ *   // Use result.path to access the repository files
+ *   const agentYaml = await readFile(join(result.path, 'agent.yaml'));
+ * } finally {
+ *   // Always clean up when done
+ *   await result.cleanup();
+ * }
+ * ```
+ */
+export async function fetchRepository(source) {
+    switch (source.type) {
+        case "github":
+            return fetchFromGitHub(source);
+        case "local":
+            return fetchFromLocal(source);
+        default: {
+            // Exhaustive check
+            const _exhaustive = source;
+            throw new Error(`Unknown source type: ${_exhaustive.type}`);
+        }
+    }
+}
+//# sourceMappingURL=repository-fetcher.js.map

package/dist/distribution/repository-fetcher.js.map

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

package/dist/distribution/repository-validator.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Repository Validation for Agent Distribution
+ *
+ * Validates that a directory is a valid agent repository by checking:
+ * - agent.yaml exists and is valid YAML conforming to AgentConfigSchema
+ * - docker.network is not "none" (agents need network access for Anthropic API)
+ * - herdctl.json is valid if present
+ * - Optional files like CLAUDE.md and README.md
+ */
+import { type AgentConfig } from "../config/schema.js";
+import { type AgentRepoMetadata } from "./agent-repo-metadata.js";
+/**
+ * Validation message representing an error or warning
+ */
+export interface ValidationMessage {
+    /** Machine-readable code like 'MISSING_AGENT_YAML', 'INVALID_AGENT_YAML' */
+    code: string;
+    /** Human-readable description of the issue */
+    message: string;
+    /** File path relative to repository root (if applicable) */
+    path?: string;
+}
+/**
+ * Result of repository validation
+ */
+export interface ValidationResult {
+    /** Whether the repository is valid for installation */
+    valid: boolean;
+    /** Agent name from agent.yaml (if valid) */
+    agentName: string | null;
+    /** Parsed agent configuration (if valid) */
+    agentConfig: AgentConfig | null;
+    /** Parsed repository metadata from herdctl.json (if present and valid) */
+    repoMetadata: AgentRepoMetadata | null;
+    /** Errors that prevent installation */
+    errors: ValidationMessage[];
+    /** Warnings the user should know about */
+    warnings: ValidationMessage[];
+}
+/** Error: agent.yaml not found */
+export declare const MISSING_AGENT_YAML = "MISSING_AGENT_YAML";
+/** Error: agent.yaml is not valid YAML */
+export declare const YAML_PARSE_ERROR = "YAML_PARSE_ERROR";
+/** Error: agent.yaml fails schema validation */
+export declare const INVALID_AGENT_YAML = "INVALID_AGENT_YAML";
+/** Error: docker.network is set to "none" */
+export declare const DOCKER_NETWORK_NONE = "DOCKER_NETWORK_NONE";
+/** Error: herdctl.json is not valid JSON */
+export declare const JSON_PARSE_ERROR = "JSON_PARSE_ERROR";
+/** Error: herdctl.json fails schema validation */
+export declare const INVALID_HERDCTL_JSON = "INVALID_HERDCTL_JSON";
+/** Warning: no herdctl.json (optional but recommended) */
+export declare const MISSING_HERDCTL_JSON = "MISSING_HERDCTL_JSON";
+/** Warning: name in agent.yaml differs from name in herdctl.json */
+export declare const NAME_MISMATCH = "NAME_MISMATCH";
+/** Warning: no CLAUDE.md file (optional but recommended) */
+export declare const MISSING_CLAUDE_MD = "MISSING_CLAUDE_MD";
+/** Warning: no README.md (optional but recommended) */
+export declare const MISSING_README = "MISSING_README";
+/**
+ * Validate a directory as an agent repository
+ *
+ * Checks that the directory contains valid agent repository files:
+ * - agent.yaml (required) - must be valid YAML conforming to AgentConfigSchema
+ * - herdctl.json (optional) - if present, must be valid JSON conforming to AgentRepoMetadataSchema
+ * - CLAUDE.md (optional) - recommended for agent identity
+ * - README.md (optional) - recommended for documentation
+ *
+ * Also performs safety checks:
+ * - docker.network cannot be "none" (agents need network for Anthropic API)
+ *
+ * @param dirPath - Absolute path to the directory to validate
+ * @returns Validation result with errors, warnings, and parsed configurations
+ *
+ * @example
+ * ```typescript
+ * const result = await validateRepository("/tmp/my-agent");
+ * if (result.valid) {
+ *   console.log(`Agent ${result.agentName} is valid`);
+ * } else {
+ *   console.error("Validation errors:", result.errors);
+ * }
+ * ```
+ */
+export declare function validateRepository(dirPath: string): Promise<ValidationResult>;
+//# sourceMappingURL=repository-validator.d.ts.map

package/dist/distribution/repository-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-validator.d.ts","sourceRoot":"","sources":["../../src/distribution/repository-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAAE,KAAK,iBAAiB,EAA2B,MAAM,0BAA0B,CAAC;AAQ3F;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4CAA4C;IAC5C,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,0EAA0E;IAC1E,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,uCAAuC;IACvC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,0CAA0C;IAC1C,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B;AAMD,kCAAkC;AAClC,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AACzD,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,kDAAkD;AAClD,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,0DAA0D;AAC1D,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,oEAAoE;AACpE,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAC7C,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,uDAAuD;AACvD,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAwE/C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2LnF"}