@herdctl/core 5.5.0 → 5.6.0

package/dist/distribution/repository-validator.js

@@ -0,0 +1,296 @@
+/**
+ * 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 { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml, YAMLParseError } from "yaml";
+import { AgentConfigSchema } from "../config/schema.js";
+import { createLogger } from "../utils/logger.js";
+import { AgentRepoMetadataSchema } from "./agent-repo-metadata.js";
+const logger = createLogger("distribution:validator");
+// =============================================================================
+// Error Codes
+// =============================================================================
+/** Error: agent.yaml not found */
+export const MISSING_AGENT_YAML = "MISSING_AGENT_YAML";
+/** Error: agent.yaml is not valid YAML */
+export const YAML_PARSE_ERROR = "YAML_PARSE_ERROR";
+/** Error: agent.yaml fails schema validation */
+export const INVALID_AGENT_YAML = "INVALID_AGENT_YAML";
+/** Error: docker.network is set to "none" */
+export const DOCKER_NETWORK_NONE = "DOCKER_NETWORK_NONE";
+/** Error: herdctl.json is not valid JSON */
+export const JSON_PARSE_ERROR = "JSON_PARSE_ERROR";
+/** Error: herdctl.json fails schema validation */
+export const INVALID_HERDCTL_JSON = "INVALID_HERDCTL_JSON";
+/** Warning: no herdctl.json (optional but recommended) */
+export const MISSING_HERDCTL_JSON = "MISSING_HERDCTL_JSON";
+/** Warning: name in agent.yaml differs from name in herdctl.json */
+export const NAME_MISMATCH = "NAME_MISMATCH";
+/** Warning: no CLAUDE.md file (optional but recommended) */
+export const MISSING_CLAUDE_MD = "MISSING_CLAUDE_MD";
+/** Warning: no README.md (optional but recommended) */
+export const MISSING_README = "MISSING_README";
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Check if a file exists
+ */
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read and parse YAML file
+ */
+async function readYamlFile(filePath) {
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const data = parseYaml(content);
+        return { success: true, data };
+    }
+    catch (err) {
+        if (err instanceof YAMLParseError) {
+            const position = err.linePos?.[0];
+            const locationInfo = position ? ` at line ${position.line}, column ${position.col}` : "";
+            return {
+                success: false,
+                error: `Invalid YAML syntax${locationInfo}: ${err.message}`,
+                isYamlError: true,
+            };
+        }
+        // File read error
+        const error = err;
+        return { success: false, error: error.message, isYamlError: false };
+    }
+}
+/**
+ * Read and parse JSON file
+ */
+async function readJsonFile(filePath) {
+    try {
+        const content = await readFile(filePath, "utf-8");
+        const data = JSON.parse(content);
+        return { success: true, data };
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            return { success: false, error: `Invalid JSON: ${err.message}`, isJsonError: true };
+        }
+        // File read error
+        const error = err;
+        return { success: false, error: error.message, isJsonError: false };
+    }
+}
+// =============================================================================
+// Main Validator
+// =============================================================================
+/**
+ * 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 async function validateRepository(dirPath) {
+    logger.debug("Validating repository", { path: dirPath });
+    const errors = [];
+    const warnings = [];
+    let agentName = null;
+    let agentConfig = null;
+    let repoMetadata = null;
+    // ==========================================================================
+    // 1. Check and validate agent.yaml (required)
+    // ==========================================================================
+    const agentYamlPath = join(dirPath, "agent.yaml");
+    const agentYamlExists = await fileExists(agentYamlPath);
+    if (!agentYamlExists) {
+        logger.debug("agent.yaml not found", { path: agentYamlPath });
+        errors.push({
+            code: MISSING_AGENT_YAML,
+            message: "Required file agent.yaml not found. Every agent repository must have an agent.yaml file.",
+            path: "agent.yaml",
+        });
+    }
+    else {
+        // Read and parse YAML
+        const yamlResult = await readYamlFile(agentYamlPath);
+        if (!yamlResult.success) {
+            logger.debug("Failed to parse agent.yaml", { error: yamlResult.error });
+            errors.push({
+                code: yamlResult.isYamlError ? YAML_PARSE_ERROR : MISSING_AGENT_YAML,
+                message: yamlResult.error,
+                path: "agent.yaml",
+            });
+        }
+        else {
+            // ==========================================================================
+            // 2. Check docker.network BEFORE schema validation (provides clearer error)
+            // Note: AgentDockerSchema doesn't include 'network' field (it's fleet-level only),
+            // but we want to give a specific error message if someone sets network: none
+            // ==========================================================================
+            const rawData = yamlResult.data;
+            const dockerConfig = rawData?.docker;
+            if (dockerConfig?.network === "none") {
+                logger.debug("docker.network is set to none", { docker: dockerConfig });
+                errors.push({
+                    code: DOCKER_NETWORK_NONE,
+                    message: 'docker.network is set to "none", which would prevent the agent from accessing Anthropic APIs. ' +
+                        "Agents require network access. Remove the network field (bridge is the default at fleet level) " +
+                        'or set it at the fleet level to "bridge" or "host".',
+                    path: "agent.yaml",
+                });
+            }
+            // Validate against AgentConfigSchema
+            const schemaResult = AgentConfigSchema.safeParse(yamlResult.data);
+            if (!schemaResult.success) {
+                const issues = schemaResult.error.issues
+                    .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+                    .join("; ");
+                logger.debug("agent.yaml schema validation failed", { issues });
+                errors.push({
+                    code: INVALID_AGENT_YAML,
+                    message: `agent.yaml validation failed: ${issues}`,
+                    path: "agent.yaml",
+                });
+            }
+            else {
+                agentConfig = schemaResult.data;
+                agentName = schemaResult.data.name;
+                logger.debug("agent.yaml is valid", { name: agentName });
+            }
+        }
+    }
+    // ==========================================================================
+    // 3. Check and validate herdctl.json (optional)
+    // ==========================================================================
+    const herdctlJsonPath = join(dirPath, "herdctl.json");
+    const herdctlJsonExists = await fileExists(herdctlJsonPath);
+    if (!herdctlJsonExists) {
+        logger.debug("herdctl.json not found (optional)", { path: herdctlJsonPath });
+        warnings.push({
+            code: MISSING_HERDCTL_JSON,
+            message: "No herdctl.json found. This file is optional but recommended for registry listing and installation metadata.",
+            path: "herdctl.json",
+        });
+    }
+    else {
+        // Read and parse JSON
+        const jsonResult = await readJsonFile(herdctlJsonPath);
+        if (!jsonResult.success) {
+            logger.debug("Failed to parse herdctl.json", { error: jsonResult.error });
+            errors.push({
+                code: jsonResult.isJsonError ? JSON_PARSE_ERROR : INVALID_HERDCTL_JSON,
+                message: jsonResult.error,
+                path: "herdctl.json",
+            });
+        }
+        else {
+            // Validate against AgentRepoMetadataSchema
+            const schemaResult = AgentRepoMetadataSchema.safeParse(jsonResult.data);
+            if (!schemaResult.success) {
+                const issues = schemaResult.error.issues
+                    .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+                    .join("; ");
+                logger.debug("herdctl.json schema validation failed", { issues });
+                errors.push({
+                    code: INVALID_HERDCTL_JSON,
+                    message: `herdctl.json validation failed: ${issues}`,
+                    path: "herdctl.json",
+                });
+            }
+            else {
+                repoMetadata = schemaResult.data;
+                logger.debug("herdctl.json is valid", { name: repoMetadata.name });
+                // ==========================================================================
+                // 4. Check name consistency between agent.yaml and herdctl.json
+                // ==========================================================================
+                if (agentName && repoMetadata.name !== agentName) {
+                    logger.debug("Name mismatch between agent.yaml and herdctl.json", {
+                        agentYaml: agentName,
+                        herdctlJson: repoMetadata.name,
+                    });
+                    warnings.push({
+                        code: NAME_MISMATCH,
+                        message: `Name mismatch: agent.yaml has name "${agentName}" but herdctl.json has name "${repoMetadata.name}". ` +
+                            `The name from agent.yaml will be used for installation.`,
+                        path: "herdctl.json",
+                    });
+                }
+            }
+        }
+    }
+    // ==========================================================================
+    // 5. Check for optional recommended files
+    // ==========================================================================
+    const claudeMdPath = join(dirPath, "CLAUDE.md");
+    const claudeMdExists = await fileExists(claudeMdPath);
+    if (!claudeMdExists) {
+        logger.debug("CLAUDE.md not found (optional)", { path: claudeMdPath });
+        warnings.push({
+            code: MISSING_CLAUDE_MD,
+            message: "No CLAUDE.md found. This file is optional but recommended for defining agent identity and behavior.",
+            path: "CLAUDE.md",
+        });
+    }
+    const readmePath = join(dirPath, "README.md");
+    const readmeExists = await fileExists(readmePath);
+    if (!readmeExists) {
+        logger.debug("README.md not found (optional)", { path: readmePath });
+        warnings.push({
+            code: MISSING_README,
+            message: "No README.md found. This file is optional but recommended for documentation.",
+            path: "README.md",
+        });
+    }
+    // ==========================================================================
+    // Build and return result
+    // ==========================================================================
+    const valid = errors.length === 0;
+    logger.info("Repository validation complete", {
+        path: dirPath,
+        valid,
+        errorCount: errors.length,
+        warningCount: warnings.length,
+        agentName,
+    });
+    return {
+        valid,
+        agentName,
+        agentConfig,
+        repoMetadata,
+        errors,
+        warnings,
+    };
+}
+//# sourceMappingURL=repository-validator.js.map

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

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

package/dist/distribution/source-specifier.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Source Specifier Parser
+ *
+ * Parses source strings into structured specifier objects for agent distribution.
+ *
+ * Supported formats:
+ * - `github:user/repo` → GitHub source (explicit prefix)
+ * - `github:user/repo@v1.0.0` → GitHub source with tag/branch/commit ref
+ * - `user/repo` → GitHub source (shorthand, equivalent to `github:user/repo`)
+ * - `user/repo@v1.0.0` → GitHub source shorthand with ref
+ * - `./local/path` or `../path` or `/absolute/path` → Local source
+ *
+ * @example
+ * ```typescript
+ * const specifier = parseSourceSpecifier("github:user/repo@v1.0.0");
+ * // { type: 'github', owner: 'user', repo: 'repo', ref: 'v1.0.0' }
+ *
+ * const shorthand = parseSourceSpecifier("user/repo");
+ * // { type: 'github', owner: 'user', repo: 'repo' }
+ *
+ * const local = parseSourceSpecifier("./my-agents/custom");
+ * // { type: 'local', path: '/resolved/absolute/path/my-agents/custom' }
+ * ```
+ */
+import { FleetManagerError } from "../fleet-manager/errors.js";
+/**
+ * GitHub source specifier.
+ * Points to a GitHub repository, optionally at a specific ref (tag, branch, or commit).
+ */
+export interface GitHubSource {
+    type: "github";
+    /** GitHub username or organization */
+    owner: string;
+    /** Repository name */
+    repo: string;
+    /** Optional ref: tag, branch name, or commit SHA */
+    ref?: string;
+}
+/**
+ * Local source specifier.
+ * Points to a local directory path (resolved to absolute).
+ */
+export interface LocalSource {
+    type: "local";
+    /** Absolute path to the local directory */
+    path: string;
+}
+/**
+ * Union type for all source specifier variants.
+ */
+export type SourceSpecifier = GitHubSource | LocalSource;
+/**
+ * Error thrown when a source specifier cannot be parsed.
+ */
+export declare class SourceParseError extends FleetManagerError {
+    readonly source: string;
+    constructor(message: string, source: string);
+}
+/**
+ * Parses a source specifier string into a structured SourceSpecifier object.
+ *
+ * @param source - The source string to parse
+ * @returns Parsed SourceSpecifier
+ * @throws SourceParseError if the source format is invalid
+ *
+ * @example
+ * ```typescript
+ * // GitHub sources
+ * parseSourceSpecifier("github:user/repo")
+ * // { type: 'github', owner: 'user', repo: 'repo' }
+ *
+ * parseSourceSpecifier("github:user/repo@v1.0.0")
+ * // { type: 'github', owner: 'user', repo: 'repo', ref: 'v1.0.0' }
+ *
+ * // Local sources
+ * parseSourceSpecifier("./local/path")
+ * // { type: 'local', path: '/resolved/absolute/path' }
+ *
+ * // GitHub shorthand
+ * parseSourceSpecifier("user/repo")
+ * // { type: 'github', owner: 'user', repo: 'repo' }
+ * ```
+ */
+export declare function parseSourceSpecifier(source: string): SourceSpecifier;
+/**
+ * Type guard for GitHubSource.
+ */
+export declare function isGitHubSource(specifier: SourceSpecifier): specifier is GitHubSource;
+/**
+ * Type guard for LocalSource.
+ */
+export declare function isLocalSource(specifier: SourceSpecifier): specifier is LocalSource;
+/**
+ * Converts a SourceSpecifier back to its string representation.
+ *
+ * @param specifier - The specifier to stringify
+ * @returns String representation of the specifier
+ *
+ * @example
+ * ```typescript
+ * stringifySourceSpecifier({ type: 'github', owner: 'user', repo: 'repo', ref: 'v1.0.0' })
+ * // "github:user/repo@v1.0.0"
+ * ```
+ */
+export declare function stringifySourceSpecifier(specifier: SourceSpecifier): string;
+//# sourceMappingURL=source-specifier.d.ts.map

package/dist/distribution/source-specifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-specifier.d.ts","sourceRoot":"","sources":["../../src/distribution/source-specifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAM/D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,CAAC;AAMzD;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB;aAGnC,MAAM,EAAE,MAAM;gBAD9B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM;CAKjC;AA2JD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAiCpE;AAMD;;GAEG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,eAAe,GAAG,SAAS,IAAI,YAAY,CAEpF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,eAAe,GAAG,SAAS,IAAI,WAAW,CAElF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,CAY3E"}

package/dist/distribution/source-specifier.js

@@ -0,0 +1,247 @@
+/**
+ * Source Specifier Parser
+ *
+ * Parses source strings into structured specifier objects for agent distribution.
+ *
+ * Supported formats:
+ * - `github:user/repo` → GitHub source (explicit prefix)
+ * - `github:user/repo@v1.0.0` → GitHub source with tag/branch/commit ref
+ * - `user/repo` → GitHub source (shorthand, equivalent to `github:user/repo`)
+ * - `user/repo@v1.0.0` → GitHub source shorthand with ref
+ * - `./local/path` or `../path` or `/absolute/path` → Local source
+ *
+ * @example
+ * ```typescript
+ * const specifier = parseSourceSpecifier("github:user/repo@v1.0.0");
+ * // { type: 'github', owner: 'user', repo: 'repo', ref: 'v1.0.0' }
+ *
+ * const shorthand = parseSourceSpecifier("user/repo");
+ * // { type: 'github', owner: 'user', repo: 'repo' }
+ *
+ * const local = parseSourceSpecifier("./my-agents/custom");
+ * // { type: 'local', path: '/resolved/absolute/path/my-agents/custom' }
+ * ```
+ */
+import * as path from "path";
+import { FleetManagerError } from "../fleet-manager/errors.js";
+// =============================================================================
+// Error Class
+// =============================================================================
+/**
+ * Error thrown when a source specifier cannot be parsed.
+ */
+export class SourceParseError extends FleetManagerError {
+    source;
+    constructor(message, source) {
+        super(message, { code: "SOURCE_PARSE_ERROR" });
+        this.source = source;
+        this.name = "SourceParseError";
+    }
+}
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Pattern for validating GitHub owner/repo names.
+ * GitHub allows: alphanumeric, hyphens, underscores, and dots.
+ * Cannot start with a dot or end with .git.
+ * Maximum 100 characters for owner, 100 for repo.
+ *
+ * @see https://docs.github.com/en/repositories/creating-and-managing-repositories/about-repositories
+ */
+const GITHUB_NAME_PATTERN = /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$|^[a-zA-Z0-9]$/;
+/**
+ * Maximum length for GitHub owner/repo names.
+ */
+const MAX_GITHUB_NAME_LENGTH = 100;
+// =============================================================================
+// Parser Implementation
+// =============================================================================
+/**
+ * Validates a GitHub owner or repository name.
+ *
+ * @param name - The name to validate
+ * @param field - Field name for error messages ("owner" or "repository")
+ * @param source - Original source string for error context
+ * @throws SourceParseError if the name is invalid
+ */
+function validateGitHubName(name, field, source) {
+    if (!name) {
+        throw new SourceParseError(`GitHub ${field} cannot be empty`, source);
+    }
+    if (name.length > MAX_GITHUB_NAME_LENGTH) {
+        throw new SourceParseError(`GitHub ${field} "${name}" exceeds maximum length of ${MAX_GITHUB_NAME_LENGTH} characters`, source);
+    }
+    if (!GITHUB_NAME_PATTERN.test(name)) {
+        throw new SourceParseError(`Invalid GitHub ${field} "${name}". ${field === "owner" ? "Owner" : "Repository"} names may only contain alphanumeric characters, hyphens, underscores, and dots, and cannot start with a dot.`, source);
+    }
+    // Additional check: cannot end with .git (GitHub convention)
+    if (name.endsWith(".git")) {
+        throw new SourceParseError(`GitHub ${field} "${name}" cannot end with ".git"`, source);
+    }
+}
+/**
+ * Parses a GitHub source specifier.
+ *
+ * @param value - The value after "github:" prefix (e.g., "user/repo" or "user/repo@v1.0.0")
+ * @param source - Original source string for error context
+ * @returns Parsed GitHubSource
+ * @throws SourceParseError if the format is invalid
+ */
+function parseGitHubSource(value, source) {
+    if (!value) {
+        throw new SourceParseError('GitHub source requires owner/repo format (e.g., "github:user/repo")', source);
+    }
+    // Split ref if present: user/repo@ref
+    let repoPath = value;
+    let ref;
+    const atIndex = value.indexOf("@");
+    if (atIndex !== -1) {
+        repoPath = value.slice(0, atIndex);
+        ref = value.slice(atIndex + 1);
+        if (!ref) {
+            throw new SourceParseError('GitHub ref cannot be empty after "@" (e.g., "github:user/repo@v1.0.0")', source);
+        }
+    }
+    // Split owner/repo
+    const slashIndex = repoPath.indexOf("/");
+    if (slashIndex === -1) {
+        throw new SourceParseError(`Invalid GitHub source format "${source}". Expected "github:owner/repo" format.`, source);
+    }
+    const owner = repoPath.slice(0, slashIndex);
+    const repo = repoPath.slice(slashIndex + 1);
+    // Check for extra slashes (nested paths not supported)
+    if (repo.includes("/")) {
+        throw new SourceParseError(`Invalid GitHub source format "${source}". Nested paths are not supported; use "github:owner/repo" format.`, source);
+    }
+    // Validate owner and repo
+    validateGitHubName(owner, "owner", source);
+    validateGitHubName(repo, "repository", source);
+    const result = { type: "github", owner, repo };
+    if (ref) {
+        result.ref = ref;
+    }
+    return result;
+}
+/**
+ * Parses a local path source specifier.
+ *
+ * @param pathStr - The path string (relative or absolute)
+ * @returns Parsed LocalSource with absolute path
+ */
+function parseLocalSource(pathStr) {
+    // Resolve to absolute path
+    const absolutePath = path.resolve(pathStr);
+    return {
+        type: "local",
+        path: absolutePath,
+    };
+}
+/**
+ * Determines if a source string represents a local path.
+ *
+ * @param source - The source string to check
+ * @returns true if the source is a local path
+ */
+function isLocalPath(source) {
+    return (source.startsWith("./") ||
+        source.startsWith("../") ||
+        source.startsWith("/") ||
+        // Windows absolute paths (e.g., C:\)
+        /^[a-zA-Z]:[/\\]/.test(source));
+}
+/**
+ * Parses a source specifier string into a structured SourceSpecifier object.
+ *
+ * @param source - The source string to parse
+ * @returns Parsed SourceSpecifier
+ * @throws SourceParseError if the source format is invalid
+ *
+ * @example
+ * ```typescript
+ * // GitHub sources
+ * parseSourceSpecifier("github:user/repo")
+ * // { type: 'github', owner: 'user', repo: 'repo' }
+ *
+ * parseSourceSpecifier("github:user/repo@v1.0.0")
+ * // { type: 'github', owner: 'user', repo: 'repo', ref: 'v1.0.0' }
+ *
+ * // Local sources
+ * parseSourceSpecifier("./local/path")
+ * // { type: 'local', path: '/resolved/absolute/path' }
+ *
+ * // GitHub shorthand
+ * parseSourceSpecifier("user/repo")
+ * // { type: 'github', owner: 'user', repo: 'repo' }
+ * ```
+ */
+export function parseSourceSpecifier(source) {
+    // Validate input
+    if (!source || typeof source !== "string") {
+        throw new SourceParseError("Source specifier cannot be empty", source || "");
+    }
+    const trimmed = source.trim();
+    if (!trimmed) {
+        throw new SourceParseError("Source specifier cannot be empty or whitespace only", source);
+    }
+    // Check for GitHub prefix
+    if (trimmed.startsWith("github:")) {
+        const value = trimmed.slice(7); // Remove "github:" prefix
+        return parseGitHubSource(value, source);
+    }
+    // Check for local path
+    if (isLocalPath(trimmed)) {
+        return parseLocalSource(trimmed);
+    }
+    // Check for GitHub shorthand (owner/repo or owner/repo@ref)
+    // A bare string containing "/" that isn't a local path is treated as GitHub shorthand
+    const slashCount = (trimmed.match(/\//g) || []).length;
+    if (slashCount === 1) {
+        return parseGitHubSource(trimmed, source);
+    }
+    throw new SourceParseError(`Unrecognized source format "${source}". Use "owner/repo", "github:owner/repo", or a local path (./path, ../path, /path).`, source);
+}
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Type guard for GitHubSource.
+ */
+export function isGitHubSource(specifier) {
+    return specifier.type === "github";
+}
+/**
+ * Type guard for LocalSource.
+ */
+export function isLocalSource(specifier) {
+    return specifier.type === "local";
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Converts a SourceSpecifier back to its string representation.
+ *
+ * @param specifier - The specifier to stringify
+ * @returns String representation of the specifier
+ *
+ * @example
+ * ```typescript
+ * stringifySourceSpecifier({ type: 'github', owner: 'user', repo: 'repo', ref: 'v1.0.0' })
+ * // "github:user/repo@v1.0.0"
+ * ```
+ */
+export function stringifySourceSpecifier(specifier) {
+    switch (specifier.type) {
+        case "github": {
+            let str = `github:${specifier.owner}/${specifier.repo}`;
+            if (specifier.ref) {
+                str += `@${specifier.ref}`;
+            }
+            return str;
+        }
+        case "local":
+            return specifier.path;
+    }
+}
+//# sourceMappingURL=source-specifier.js.map