@herdctl/core 5.4.3 → 5.6.0

package/dist/distribution/env-scanner.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Environment Variable Scanner
+ *
+ * Scans agent.yaml content (as raw text) and extracts all ${VAR} and ${VAR:-default}
+ * references. Used to inform users which environment variables they need to set
+ * after installing an agent.
+ *
+ * @example
+ * ```typescript
+ * const yamlContent = `
+ * name: my-agent
+ * env:
+ *   webhook: \${DISCORD_WEBHOOK_URL}
+ *   token: \${API_TOKEN:-default-token}
+ * `;
+ *
+ * const result = scanEnvVariables(yamlContent);
+ * // result = {
+ * //   variables: [
+ * //     { name: "API_TOKEN", defaultValue: "default-token" },
+ * //     { name: "DISCORD_WEBHOOK_URL" }
+ * //   ],
+ * //   required: [{ name: "DISCORD_WEBHOOK_URL" }],
+ * //   optional: [{ name: "API_TOKEN", defaultValue: "default-token" }]
+ * // }
+ * ```
+ */
+/**
+ * Represents an environment variable reference found in the YAML content.
+ */
+export interface EnvVariable {
+    /** The variable name (e.g., "DISCORD_WEBHOOK_URL") */
+    name: string;
+    /** The default value if specified with :- syntax, or undefined */
+    defaultValue?: string;
+}
+/**
+ * Result of scanning YAML content for environment variable references.
+ */
+export interface EnvScanResult {
+    /** All unique environment variables found, sorted alphabetically */
+    variables: EnvVariable[];
+    /** Variables that have no default value (user MUST set these) */
+    required: EnvVariable[];
+    /** Variables that have a default value (optional to set) */
+    optional: EnvVariable[];
+}
+/**
+ * Scans YAML content for environment variable references.
+ *
+ * This function scans raw text (not parsed YAML) to extract all ${VAR} and
+ * ${VAR:-default} patterns. It:
+ * - Deduplicates variables (same name only listed once)
+ * - Prefers entries with defaults when a variable appears both with and without
+ * - Sorts alphabetically by variable name
+ * - Partitions into required (no default) and optional (has default) lists
+ * - Excludes HERDCTL_* prefixed variables (internal to herdctl)
+ *
+ * @param yamlContent - The raw YAML file content to scan
+ * @returns EnvScanResult with variables, required, and optional arrays
+ *
+ * @example
+ * ```typescript
+ * const result = scanEnvVariables(`
+ *   webhook: \${WEBHOOK_URL}
+ *   api_key: \${API_KEY:-sk-default}
+ *   # Comment with \${COMMENT_VAR}
+ * `);
+ *
+ * // result.variables = [
+ * //   { name: "API_KEY", defaultValue: "sk-default" },
+ * //   { name: "COMMENT_VAR" },
+ * //   { name: "WEBHOOK_URL" }
+ * // ]
+ * ```
+ */
+export declare function scanEnvVariables(yamlContent: string): EnvScanResult;
+//# sourceMappingURL=env-scanner.d.ts.map

package/dist/distribution/env-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-scanner.d.ts","sourceRoot":"","sources":["../../src/distribution/env-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,iEAAiE;IACjE,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAoCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAiEnE"}

package/dist/distribution/env-scanner.js

@@ -0,0 +1,144 @@
+/**
+ * Environment Variable Scanner
+ *
+ * Scans agent.yaml content (as raw text) and extracts all ${VAR} and ${VAR:-default}
+ * references. Used to inform users which environment variables they need to set
+ * after installing an agent.
+ *
+ * @example
+ * ```typescript
+ * const yamlContent = `
+ * name: my-agent
+ * env:
+ *   webhook: \${DISCORD_WEBHOOK_URL}
+ *   token: \${API_TOKEN:-default-token}
+ * `;
+ *
+ * const result = scanEnvVariables(yamlContent);
+ * // result = {
+ * //   variables: [
+ * //     { name: "API_TOKEN", defaultValue: "default-token" },
+ * //     { name: "DISCORD_WEBHOOK_URL" }
+ * //   ],
+ * //   required: [{ name: "DISCORD_WEBHOOK_URL" }],
+ * //   optional: [{ name: "API_TOKEN", defaultValue: "default-token" }]
+ * // }
+ * ```
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Regular expression to match ${VAR} and ${VAR:-default} patterns.
+ * This is the same pattern used in packages/core/src/config/interpolate.ts.
+ *
+ * Captures:
+ * - Group 1: Variable name (letters, numbers, underscores, starting with letter or underscore)
+ * - Group 2: Default value (everything after :- if present)
+ */
+const ENV_VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+/**
+ * Variables to exclude from scan results.
+ * These are herdctl-internal variables, not agent-specific configuration.
+ */
+const EXCLUDED_PREFIXES = ["HERDCTL_"];
+// =============================================================================
+// Implementation
+// =============================================================================
+/**
+ * Checks if a variable name should be excluded from results.
+ *
+ * @param name - The variable name to check
+ * @returns true if the variable should be excluded
+ */
+function shouldExclude(name) {
+    return EXCLUDED_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+/**
+ * Scans YAML content for environment variable references.
+ *
+ * This function scans raw text (not parsed YAML) to extract all ${VAR} and
+ * ${VAR:-default} patterns. It:
+ * - Deduplicates variables (same name only listed once)
+ * - Prefers entries with defaults when a variable appears both with and without
+ * - Sorts alphabetically by variable name
+ * - Partitions into required (no default) and optional (has default) lists
+ * - Excludes HERDCTL_* prefixed variables (internal to herdctl)
+ *
+ * @param yamlContent - The raw YAML file content to scan
+ * @returns EnvScanResult with variables, required, and optional arrays
+ *
+ * @example
+ * ```typescript
+ * const result = scanEnvVariables(`
+ *   webhook: \${WEBHOOK_URL}
+ *   api_key: \${API_KEY:-sk-default}
+ *   # Comment with \${COMMENT_VAR}
+ * `);
+ *
+ * // result.variables = [
+ * //   { name: "API_KEY", defaultValue: "sk-default" },
+ * //   { name: "COMMENT_VAR" },
+ * //   { name: "WEBHOOK_URL" }
+ * // ]
+ * ```
+ */
+export function scanEnvVariables(yamlContent) {
+    // Handle empty or non-string input
+    if (!yamlContent || typeof yamlContent !== "string") {
+        return {
+            variables: [],
+            required: [],
+            optional: [],
+        };
+    }
+    // Map to track unique variables, preferring entries with defaults
+    const variableMap = new Map();
+    // Reset regex state (global regexes are stateful)
+    ENV_VAR_PATTERN.lastIndex = 0;
+    // Find all matches
+    let match = null;
+    while ((match = ENV_VAR_PATTERN.exec(yamlContent)) !== null) {
+        const name = match[1];
+        const defaultValue = match[2];
+        // Skip excluded variables
+        if (shouldExclude(name)) {
+            continue;
+        }
+        const existing = variableMap.get(name);
+        // If variable already exists, prefer the entry with a default value
+        if (existing) {
+            if (defaultValue !== undefined && existing.defaultValue === undefined) {
+                variableMap.set(name, { name, defaultValue });
+            }
+            // Otherwise keep existing (either already has default, or neither has default)
+        }
+        else {
+            // First occurrence of this variable
+            const variable = { name };
+            if (defaultValue !== undefined) {
+                variable.defaultValue = defaultValue;
+            }
+            variableMap.set(name, variable);
+        }
+    }
+    // Convert to array and sort alphabetically by name
+    const variables = Array.from(variableMap.values()).sort((a, b) => a.name.localeCompare(b.name));
+    // Partition into required and optional
+    const required = [];
+    const optional = [];
+    for (const variable of variables) {
+        if (variable.defaultValue !== undefined) {
+            optional.push(variable);
+        }
+        else {
+            required.push(variable);
+        }
+    }
+    return {
+        variables,
+        required,
+        optional,
+    };
+}
+//# sourceMappingURL=env-scanner.js.map

package/dist/distribution/env-scanner.js.map

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

package/dist/distribution/file-installer.d.ts

@@ -0,0 +1,80 @@
+/**
+ * File Installation for Agent Distribution
+ *
+ * Copies agent files from a fetched/temp directory to `./agents/<name>/` in the
+ * user's project. Creates the workspace directory and writes installation metadata.
+ */
+import { FleetManagerError, type FleetManagerErrorCode } from "../fleet-manager/errors.js";
+import type { InstallationSource } from "./installation-metadata.js";
+/**
+ * Options for installing agent files
+ */
+export interface InstallOptions {
+    /** The directory containing the fetched agent repo files */
+    sourceDir: string;
+    /** The target base directory (where agents/ lives, usually project root) */
+    targetBaseDir: string;
+    /** The source specifier info for metadata tracking */
+    source: InstallationSource;
+    /** Optional: override the target path instead of using ./agents/<name>/ */
+    targetPath?: string;
+    /** If true, remove existing target directory before installing */
+    force?: boolean;
+}
+/**
+ * Result of a successful agent file installation
+ */
+export interface InstallResult {
+    /** The agent name (from agent.yaml) */
+    agentName: string;
+    /** The full path to the installed agent directory */
+    installPath: string;
+    /** List of files that were copied (relative paths) */
+    copiedFiles: string[];
+}
+/**
+ * Error codes for agent installation failures
+ */
+export declare const AGENT_ALREADY_EXISTS: FleetManagerErrorCode;
+export declare const INVALID_AGENT_NAME: FleetManagerErrorCode;
+export declare const MISSING_AGENT_YAML: FleetManagerErrorCode;
+export declare const INVALID_AGENT_YAML: FleetManagerErrorCode;
+/**
+ * Error thrown when agent file installation fails
+ */
+export declare class AgentInstallError extends FleetManagerError {
+    constructor(message: string, code: FleetManagerErrorCode);
+}
+/**
+ * Install agent files from a source directory to the target location
+ *
+ * This function:
+ * 1. Reads the agent name from `agent.yaml` in the source directory
+ * 2. Validates the agent name against AGENT_NAME_PATTERN
+ * 3. Checks that the target directory doesn't already exist
+ * 4. Copies all files from source to target, excluding `.git/` and `node_modules/`
+ * 5. Creates an empty `workspace/` directory for agent runtime use
+ * 6. Writes `metadata.json` with installation tracking information
+ *
+ * @param options - Installation options
+ * @returns Installation result with agent name, install path, and copied files
+ * @throws {AgentInstallError} When installation fails
+ *
+ * @example
+ * ```typescript
+ * const result = await installAgentFiles({
+ *   sourceDir: "/tmp/herdctl-github-xxxxx",
+ *   targetBaseDir: "/path/to/project",
+ *   source: {
+ *     type: "github",
+ *     url: "https://github.com/user/agent-repo",
+ *     ref: "v1.0.0"
+ *   }
+ * });
+ *
+ * console.log(`Installed ${result.agentName} to ${result.installPath}`);
+ * console.log(`Copied ${result.copiedFiles.length} files`);
+ * ```
+ */
+export declare function installAgentFiles(options: InstallOptions): Promise<InstallResult>;
+//# sourceMappingURL=file-installer.d.ts.map

package/dist/distribution/file-installer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-installer.d.ts","sourceRoot":"","sources":["../../src/distribution/file-installer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAG3F,OAAO,KAAK,EAAwB,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAQ3F;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,MAAM,EAAE,kBAAkB,CAAC;IAC3B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAMD;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,qBAA8C,CAAC;AAClF,eAAO,MAAM,kBAAkB,EAAE,qBAA4C,CAAC;AAC9E,eAAO,MAAM,kBAAkB,EAAE,qBAA4C,CAAC;AAC9E,eAAO,MAAM,kBAAkB,EAAE,qBAA4C,CAAC;AAE9E;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,iBAAiB;gBAC1C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB;CAIzD;AA8LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CA+EvF"}

package/dist/distribution/file-installer.js

@@ -0,0 +1,268 @@
+/**
+ * File Installation for Agent Distribution
+ *
+ * Copies agent files from a fetched/temp directory to `./agents/<name>/` in the
+ * user's project. Creates the workspace directory and writes installation metadata.
+ */
+import { access, cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml, YAMLParseError } from "yaml";
+import { FleetManagerError } from "../fleet-manager/errors.js";
+import { createLogger } from "../utils/logger.js";
+import { AGENT_NAME_PATTERN } from "./agent-repo-metadata.js";
+const logger = createLogger("distribution:installer");
+// =============================================================================
+// Error Classes
+// =============================================================================
+/**
+ * Error codes for agent installation failures
+ */
+export const AGENT_ALREADY_EXISTS = "AGENT_ALREADY_EXISTS";
+export const INVALID_AGENT_NAME = "INVALID_AGENT_NAME";
+export const MISSING_AGENT_YAML = "MISSING_AGENT_YAML";
+export const INVALID_AGENT_YAML = "INVALID_AGENT_YAML";
+/**
+ * Error thrown when agent file installation fails
+ */
+export class AgentInstallError extends FleetManagerError {
+    constructor(message, code) {
+        super(message, { code });
+        this.name = "AgentInstallError";
+    }
+}
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Directories to exclude when copying agent files
+ */
+const EXCLUDED_DIRS = new Set([".git", "node_modules"]);
+/**
+ * Metadata file name for installation tracking
+ */
+const METADATA_FILE = "metadata.json";
+/**
+ * Workspace directory name (created for agent runtime use)
+ */
+const WORKSPACE_DIR = "workspace";
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Check if a path exists
+ */
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read and parse agent.yaml to extract the agent name
+ */
+async function readAgentName(sourceDir) {
+    const agentYamlPath = join(sourceDir, "agent.yaml");
+    // Check if agent.yaml exists
+    if (!(await pathExists(agentYamlPath))) {
+        throw new AgentInstallError(`agent.yaml not found in source directory: ${sourceDir}`, MISSING_AGENT_YAML);
+    }
+    // Read and parse the file
+    let content;
+    try {
+        content = await readFile(agentYamlPath, "utf-8");
+    }
+    catch (err) {
+        const error = err;
+        throw new AgentInstallError(`Failed to read agent.yaml: ${error.message}`, MISSING_AGENT_YAML);
+    }
+    // Parse YAML
+    let parsed;
+    try {
+        parsed = parseYaml(content);
+    }
+    catch (err) {
+        if (err instanceof YAMLParseError) {
+            const position = err.linePos?.[0];
+            const locationInfo = position ? ` at line ${position.line}, column ${position.col}` : "";
+            throw new AgentInstallError(`Invalid YAML syntax in agent.yaml${locationInfo}: ${err.message}`, INVALID_AGENT_YAML);
+        }
+        throw new AgentInstallError(`Failed to parse agent.yaml: ${err.message}`, INVALID_AGENT_YAML);
+    }
+    // Extract and validate name
+    if (!parsed || typeof parsed !== "object") {
+        throw new AgentInstallError("agent.yaml must contain a valid YAML object with a 'name' field", INVALID_AGENT_YAML);
+    }
+    const data = parsed;
+    const name = data.name;
+    if (typeof name !== "string" || name.trim() === "") {
+        throw new AgentInstallError("agent.yaml must have a 'name' field with a non-empty string value", INVALID_AGENT_YAML);
+    }
+    return name;
+}
+/**
+ * Validate an agent name against the AGENT_NAME_PATTERN
+ */
+function validateAgentName(name) {
+    if (!AGENT_NAME_PATTERN.test(name)) {
+        throw new AgentInstallError(`Invalid agent name "${name}". Agent names must start with a letter or number ` +
+            `and contain only letters, numbers, underscores, and hyphens.`, INVALID_AGENT_NAME);
+    }
+}
+/**
+ * Recursively copy directory contents, excluding specified directories.
+ * Returns the list of copied files (relative paths).
+ */
+async function copyDirectoryRecursive(sourceDir, targetDir, excludedDirs, relativePath = "") {
+    const copiedFiles = [];
+    // Create target directory if it doesn't exist
+    await mkdir(targetDir, { recursive: true });
+    // Read source directory contents
+    const entries = await readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = join(sourceDir, entry.name);
+        const targetPath = join(targetDir, entry.name);
+        const entryRelativePath = relativePath ? join(relativePath, entry.name) : entry.name;
+        if (entry.isDirectory()) {
+            // Skip excluded directories
+            if (excludedDirs.has(entry.name)) {
+                logger.debug("Skipping excluded directory", { path: entryRelativePath });
+                continue;
+            }
+            // Recursively copy subdirectory
+            const subFiles = await copyDirectoryRecursive(sourcePath, targetPath, excludedDirs, entryRelativePath);
+            copiedFiles.push(...subFiles);
+        }
+        else if (entry.isFile()) {
+            // Copy file
+            await cp(sourcePath, targetPath);
+            copiedFiles.push(entryRelativePath);
+        }
+        // Skip symlinks and other special files
+    }
+    return copiedFiles;
+}
+/**
+ * Write installation metadata to metadata.json
+ */
+async function writeMetadata(installPath, source) {
+    const metadata = {
+        source,
+        installed_at: new Date().toISOString(),
+        installed_by: `herdctl@${getHerdctlVersion()}`,
+    };
+    const metadataPath = join(installPath, METADATA_FILE);
+    await writeFile(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
+    logger.debug("Wrote metadata.json", { path: metadataPath });
+}
+/**
+ * Get herdctl version from package.json (simplified - returns unknown if not found)
+ */
+function getHerdctlVersion() {
+    // In a real implementation, this would read from package.json
+    // For now, we return a placeholder that will be replaced with actual version
+    return "unknown";
+}
+// =============================================================================
+// Main Installer
+// =============================================================================
+/**
+ * Install agent files from a source directory to the target location
+ *
+ * This function:
+ * 1. Reads the agent name from `agent.yaml` in the source directory
+ * 2. Validates the agent name against AGENT_NAME_PATTERN
+ * 3. Checks that the target directory doesn't already exist
+ * 4. Copies all files from source to target, excluding `.git/` and `node_modules/`
+ * 5. Creates an empty `workspace/` directory for agent runtime use
+ * 6. Writes `metadata.json` with installation tracking information
+ *
+ * @param options - Installation options
+ * @returns Installation result with agent name, install path, and copied files
+ * @throws {AgentInstallError} When installation fails
+ *
+ * @example
+ * ```typescript
+ * const result = await installAgentFiles({
+ *   sourceDir: "/tmp/herdctl-github-xxxxx",
+ *   targetBaseDir: "/path/to/project",
+ *   source: {
+ *     type: "github",
+ *     url: "https://github.com/user/agent-repo",
+ *     ref: "v1.0.0"
+ *   }
+ * });
+ *
+ * console.log(`Installed ${result.agentName} to ${result.installPath}`);
+ * console.log(`Copied ${result.copiedFiles.length} files`);
+ * ```
+ */
+export async function installAgentFiles(options) {
+    const { sourceDir, targetBaseDir, source, targetPath, force } = options;
+    logger.debug("Starting agent file installation", {
+        sourceDir,
+        targetBaseDir,
+        sourceType: source.type,
+        targetPath,
+        force,
+    });
+    // ==========================================================================
+    // 1. Read agent name from agent.yaml
+    // ==========================================================================
+    const agentName = await readAgentName(sourceDir);
+    logger.debug("Read agent name from agent.yaml", { agentName });
+    // ==========================================================================
+    // 2. Validate agent name
+    // ==========================================================================
+    validateAgentName(agentName);
+    logger.debug("Agent name validated", { agentName });
+    // ==========================================================================
+    // 3. Determine target path and check it doesn't exist (unless force)
+    // ==========================================================================
+    const installPath = targetPath ?? join(targetBaseDir, "agents", agentName);
+    if (await pathExists(installPath)) {
+        if (force) {
+            // Remove existing directory when force is true
+            logger.debug("Force mode: removing existing directory", { installPath });
+            const { rm } = await import("node:fs/promises");
+            await rm(installPath, { recursive: true, force: true });
+        }
+        else {
+            throw new AgentInstallError(`Agent "${agentName}" already exists at ${installPath}. ` +
+                `Remove the existing agent first or use a different name.`, AGENT_ALREADY_EXISTS);
+        }
+    }
+    logger.debug("Target path determined", { installPath });
+    // ==========================================================================
+    // 4. Copy files (excluding .git and node_modules)
+    // ==========================================================================
+    logger.info("Copying agent files", {
+        source: sourceDir,
+        destination: installPath,
+    });
+    const copiedFiles = await copyDirectoryRecursive(sourceDir, installPath, EXCLUDED_DIRS);
+    logger.debug("Files copied", { count: copiedFiles.length });
+    // ==========================================================================
+    // 5. Create workspace directory
+    // ==========================================================================
+    const workspacePath = join(installPath, WORKSPACE_DIR);
+    await mkdir(workspacePath, { recursive: true });
+    logger.debug("Created workspace directory", { path: workspacePath });
+    // ==========================================================================
+    // 6. Write metadata.json
+    // ==========================================================================
+    await writeMetadata(installPath, source);
+    logger.info("Agent installation complete", {
+        agentName,
+        installPath,
+        copiedFiles: copiedFiles.length,
+    });
+    return {
+        agentName,
+        installPath,
+        copiedFiles,
+    };
+}
+//# sourceMappingURL=file-installer.js.map

package/dist/distribution/file-installer.js.map

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