@standardagents/builder 0.11.12 → 0.12.1

package/dist/packing.d.ts

@@ -0,0 +1,266 @@
+import { P as PackingAnalysis, a as PackingOptions, b as PackingResult, d as UnpackAnalysis, U as UnpackOptions, c as UnpackResult } from './types-pLkJx8vg.js';
+export { D as DiscoveredPackage } from './types-pLkJx8vg.js';
+export { P as PackageDiscoveryService, d as discoverPackages } from './discovery-CpMs68Yx.js';
+import '@standardagents/spec';
+
+/**
+ * Packing service for Standard Agents.
+ *
+ * Provides functionality to:
+ * - Analyze agents and their dependencies
+ * - Pack agents with all constituents using Rollup bundling
+ * - Generate npm-ready package structures with TypeScript definitions
+ *
+ * The new Rollup-based approach:
+ * - Preserves imports, constants, and helper functions
+ * - Bundles local dependencies inline
+ * - Keeps npm packages as external dependencies
+ * - Creates separate files per constituent with re-exports in index.ts
+ *
+ * @module
+ */
+
+/**
+ * Service for packing agents with their dependencies.
+ */
+declare class PackingService {
+    /**
+     * Resolve the version of an npm package from node_modules.
+     *
+     * @param pkgName - Package name (e.g., '@standardagents/spec')
+     * @param rootDir - Root directory of the project
+     * @returns Version specifier (e.g., '^1.2.3') or '*' if not found
+     */
+    protected resolvePackageVersion(pkgName: string, rootDir: string): string;
+    /**
+     * Analyze an agent to discover all its constituents.
+     *
+     * This performs static analysis on the agent definition and all
+     * referenced prompts, tools, models, and hooks.
+     *
+     * @param agentName - Name of the agent to analyze
+     * @param rootDir - Root directory of the agents workspace
+     * @returns Analysis result with all discovered constituents
+     */
+    analyzeAgent(agentName: string, rootDir: string): Promise<PackingAnalysis>;
+    /**
+     * Generate a README for an analyzed agent.
+     *
+     * This is used during analysis to provide a pre-populated README
+     * that can be edited in the PackModal before packing.
+     *
+     * @param analysis - The packing analysis result
+     * @param rootDir - Root directory of the project
+     * @returns Object with generatedReadme and agentDescription
+     */
+    generateReadmeForAnalysis(analysis: PackingAnalysis, rootDir: string): {
+        generatedReadme: string;
+        agentDescription?: string;
+    };
+    /**
+     * Recursively analyze a prompt and its dependencies.
+     */
+    private analyzePrompt;
+    /**
+     * Analyze a tool and its dependencies.
+     * This also handles prompts-as-tools and agents-as-tools (handoffs).
+     */
+    private analyzeTool;
+    /**
+     * Analyze a nested agent (used as a handoff target).
+     */
+    private analyzeNestedAgent;
+    /**
+     * Analyze a model and its fallbacks.
+     */
+    private analyzeModel;
+    /**
+     * Check which items are shared with other agents.
+     */
+    private checkSharedItems;
+    /**
+     * Light analysis of an agent - just get the names of used items.
+     */
+    private analyzeAgentLight;
+    /**
+     * Pack an agent with all its dependencies using Rollup bundling.
+     *
+     * The packing format creates:
+     * - dist/{type}/{name}.js - Individual bundled files per constituent
+     * - dist/index.js - Re-exports and lazy loaders
+     * - dist/index.d.ts - TypeScript type definitions
+     * - package.json - With standardagent field and dependencies
+     * - tsconfig.json - For building
+     *
+     * @param options - Packing options
+     * @returns Packing result
+     */
+    pack(options: PackingOptions): Promise<PackingResult>;
+    /**
+     * Bundle a single source file with its local dependencies using Rollup.
+     *
+     * Local files (from the same agents/ directory) are inlined.
+     * npm packages are kept as external dependencies.
+     * Output is bundled JavaScript with all local deps inlined.
+     *
+     * @returns Map of external dependencies (name -> version specifier)
+     */
+    protected bundleFile(inputPath: string, outputPath: string, rootDir: string): Promise<Map<string, string>>;
+    /**
+     * Get the directory name for a constituent type.
+     */
+    private getTypeDir;
+    /**
+     * Deduplicate constituents by name (for packing, not for tree display).
+     */
+    private deduplicateConstituents;
+    /**
+     * Check if a name is a valid JavaScript/TypeScript identifier.
+     */
+    private isValidIdentifier;
+    /**
+     * Quote a property/export name if it contains non-identifier characters.
+     * JavaScript identifiers must start with a letter, underscore, or dollar sign,
+     * and contain only letters, digits, underscores, or dollar signs.
+     */
+    private quoteName;
+    /**
+     * Generate the dist/index.js file with re-exports and lazy loaders.
+     */
+    private generateReExportIndex;
+    /**
+     * Generate the dist/index.d.ts file with type definitions.
+     */
+    private generateIndexDts;
+    /**
+     * Generate the package.json file with dependencies.
+     */
+    private generatePackageJson;
+    /**
+     * Generate LICENSE file content for common licenses.
+     */
+    private generateLicenseFile;
+    /**
+     * Get information about a packed package.
+     *
+     * Reads the package.json and README.md from a packed package directory.
+     * Used by the packed-info API endpoint to show package details before publishing.
+     *
+     * @param packageId - The package directory name (e.g., 'standardagent-my-agent')
+     * @param rootDir - Root directory of the project
+     * @returns Package info or null if not found
+     */
+    getPackedInfo(packageId: string, rootDir: string): {
+        packageName: string;
+        version: string;
+        license?: string;
+        author?: string;
+        entryAgents: string[];
+        readme?: string;
+    } | null;
+    /**
+     * List all packed packages in the workspace.
+     *
+     * @param rootDir - Root directory of the project
+     * @returns Array of package directory names
+     */
+    listPackedPackages(rootDir: string): string[];
+    /**
+     * Generate README.md content for a packed agent.
+     *
+     * @param packageName - The npm package name
+     * @param agentName - The agent name
+     * @param version - The package version
+     * @param license - The license type
+     * @param description - Optional description from the agent definition
+     * @returns README markdown content
+     */
+    generateReadme(packageName: string, agentName: string, version: string, license?: string, description?: string): string;
+    /**
+     * Find a file by name in a directory.
+     */
+    private findFile;
+    /**
+     * List all agents in the workspace.
+     */
+    listAgents(rootDir: string): string[];
+}
+
+/**
+ * Unpacking service for Standard Agents.
+ *
+ * Provides functionality to:
+ * - Analyze packed packages to discover exportable items
+ * - Transform bundled JavaScript back to TypeScript source files
+ * - Restore packed agents to editable source files
+ *
+ * Uses AST-based transformation (TypeScript Compiler API + magic-string)
+ * to accurately preserve all code including Zod schemas and execute functions.
+ *
+ * @module
+ */
+
+/**
+ * Service for unpacking packed agent packages.
+ */
+declare class UnpackingService {
+    /**
+     * Analyze a package to discover what can be unpacked.
+     *
+     * @param packageId - Package ID to analyze
+     * @param rootDir - Root directory of the agents workspace
+     * @returns Analysis result with items that can be unpacked
+     */
+    analyzeUnpack(packageId: string, rootDir: string): Promise<UnpackAnalysis>;
+    /**
+     * Discover relationships from a bundled file.
+     * Returns child items that this item references.
+     */
+    private discoverRelationships;
+    /**
+     * Unpack a packed agent package by transforming bundled JS back to TypeScript.
+     *
+     * @param options - Unpacking options
+     * @returns Result of the unpacking operation
+     */
+    unpack(options: UnpackOptions): Promise<UnpackResult>;
+    /**
+     * Parse the index.js file to extract registry items.
+     *
+     * Looks for patterns like:
+     * ```javascript
+     * export const agents = {
+     *   support_agent: async () => (await import('./agents/support_agent.js')).default,
+     * };
+     * ```
+     */
+    private parseIndexExports;
+    /**
+     * Resolve a package identifier to a discovered package.
+     */
+    private resolvePackage;
+    /**
+     * Apply user selections to items.
+     */
+    private applySelections;
+    /**
+     * Check if a file exists.
+     */
+    private fileExists;
+    /**
+     * Recursively delete a directory.
+     */
+    private deleteDirectory;
+    /**
+     * List available packed packages.
+     */
+    listPackages(rootDir: string): Promise<Array<{
+        packageId: string;
+        version: string;
+        source: 'npm' | 'local';
+        entryAgents: string[];
+        path: string;
+    }>>;
+}
+
+export { PackingAnalysis, PackingOptions, PackingResult, PackingService, UnpackOptions, UnpackResult, UnpackingService };