lua-cli 3.5.0-alpha.3 → 3.5.0-beta.1

package/dist/types/yaml.types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Type definitions for YAML configuration (lua.skill.yaml)
+ */
+/**
+ * Legacy single-skill format (for backward compatibility)
+ */
+export interface LegacyYamlConfigSkill {
+    name?: string;
+    version?: string;
+    skillId?: string;
+}
+export interface YamlConfigAgent {
+    agentId?: string;
+    orgId?: string;
+    persona?: string;
+}
+export interface YamlConfigSkill {
+    name: string;
+    version: string;
+    skillId: string;
+}
+export interface YamlConfigWebhook {
+    name: string;
+    version: string;
+    webhookId: string;
+    description?: string;
+}
+export interface YamlConfigJob {
+    name: string;
+    version: string;
+    jobId: string;
+    schedule?: any;
+    description?: string;
+    metadata?: any;
+}
+export interface YamlConfigPreprocessor {
+    name: string;
+    version: string;
+    preprocessorId: string;
+    description?: string;
+}
+export interface YamlConfigPostprocessor {
+    name: string;
+    version: string;
+    postprocessorId: string;
+    description?: string;
+}
+export interface YamlConfigMCPServer {
+    name: string;
+    mcpServerId: string;
+}
+export interface YamlConfigBackup {
+    /** Hash of last pushed backup */
+    lastHash?: string;
+    /** Timestamp of last backup push */
+    lastPushedAt?: string;
+}
+export interface YamlConfig {
+    skill?: LegacyYamlConfigSkill;
+    agent?: YamlConfigAgent;
+    skills?: YamlConfigSkill[];
+    webhooks?: YamlConfigWebhook[];
+    jobs?: YamlConfigJob[];
+    preprocessors?: YamlConfigPreprocessor[];
+    postprocessors?: YamlConfigPostprocessor[];
+    mcpServers?: YamlConfigMCPServer[];
+    /** Backup tracking information */
+    backup?: YamlConfigBackup;
+}

package/dist/types/yaml.types.js

@@ -0,0 +1,6 @@
+/**
+ * Type definitions for YAML configuration (lua.skill.yaml)
+ */
+;
+export {};
+//# sourceMappingURL=yaml.types.js.map

package/dist/types/yaml.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.types.js","sourceRoot":"","sources":["../../src/types/yaml.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeF,CAAC"}

package/dist/utils/artifact-loader.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Artifact Loader Utilities
+ *
+ * Utilities for loading compilation artifacts from the new compiler output (dist-v2/).
+ * Used by push, test, and dev commands.
+ */
+import type { CompilationManifest, ManifestPrimitive } from '../compiler/types.js';
+import { PrimitiveKind } from '../compiler/types.js';
+/**
+ * Load the compilation manifest from dist-v2/manifest.json.
+ *
+ * @param projectPath - Path to the project root (defaults to cwd)
+ * @returns The compilation manifest
+ * @throws Error if manifest not found or invalid
+ */
+export declare function loadManifest(projectPath?: string): CompilationManifest;
+/**
+ * Check if the compilation output exists.
+ *
+ * @param projectPath - Path to the project root
+ * @returns true if dist-v2/manifest.json exists
+ */
+export declare function hasCompilationOutput(projectPath?: string): boolean;
+/**
+ * Load a primitive artifact (bundled JS code) from disk.
+ *
+ * @param primitive - The primitive from the manifest
+ * @param projectPath - Path to the project root
+ * @returns The artifact code as a string
+ */
+export declare function loadArtifact(primitive: ManifestPrimitive, projectPath?: string): string;
+/**
+ * Load a primitive artifact and its metadata JSON.
+ *
+ * @param primitive - The primitive from the manifest
+ * @param projectPath - Path to the project root
+ * @returns Object with code and metadata
+ */
+export declare function loadArtifactWithMetadata(primitive: ManifestPrimitive, projectPath?: string): {
+    code: string;
+    metadata: Record<string, any>;
+};
+/**
+ * Load source map for a primitive (if it exists).
+ *
+ * @param primitive - The primitive from the manifest
+ * @param projectPath - Path to the project root
+ * @returns The source map string or null if not found
+ */
+export declare function loadSourceMap(primitive: ManifestPrimitive, projectPath?: string): string | null;
+/**
+ * Compress code for pushing to server.
+ * Uses gzip + base64 encoding (matches server expectation).
+ *
+ * @param code - The artifact code to compress
+ * @returns Base64-encoded gzipped code
+ */
+export declare function compressForPush(code: string): string;
+/**
+ * Decompress code from server format.
+ *
+ * @param compressed - Base64-encoded gzipped code
+ * @returns The decompressed code
+ */
+export declare function decompressFromServer(compressed: string): string;
+/**
+ * Get primitives of a specific kind from the manifest.
+ *
+ * @param manifest - The compilation manifest
+ * @param kind - The primitive kind to filter by
+ * @returns Array of primitives matching the kind
+ */
+export declare function getPrimitivesByKind<T extends ManifestPrimitive>(manifest: CompilationManifest, kind: PrimitiveKind): T[];
+/**
+ * Find a primitive by name and kind.
+ *
+ * @param manifest - The compilation manifest
+ * @param name - The primitive name
+ * @param kind - Optional kind to filter by
+ * @returns The primitive or undefined
+ */
+export declare function findPrimitive<T extends ManifestPrimitive>(manifest: CompilationManifest, name: string, kind?: T['kind']): T | undefined;
+/**
+ * Get the agent name from the compilation manifest.
+ *
+ * @param projectPath - Path to the project root (defaults to cwd)
+ * @returns The agent name, or null if not found or no manifest
+ */
+export declare function getAgentName(projectPath?: string): string | null;
+/**
+ * Get the agent persona from the compilation manifest.
+ *
+ * @param projectPath - Path to the project root (defaults to cwd)
+ * @returns The agent persona, or null if not found or no manifest
+ */
+export declare function getAgentPersona(projectPath?: string): string | null;
+/**
+ * Load all artifacts of a specific kind.
+ *
+ * @param manifest - The compilation manifest
+ * @param kind - The primitive kind
+ * @param projectPath - Path to the project root
+ * @returns Array of { primitive, code } objects
+ */
+export declare function loadAllArtifactsOfKind(manifest: CompilationManifest, kind: PrimitiveKind, projectPath?: string): Array<{
+    primitive: ManifestPrimitive;
+    code: string;
+}>;

package/dist/utils/artifact-loader.js

@@ -0,0 +1,188 @@
+/**
+ * Artifact Loader Utilities
+ *
+ * Utilities for loading compilation artifacts from the new compiler output (dist-v2/).
+ * Used by push, test, and dev commands.
+ */
+import fs from 'fs';
+import path from 'path';
+import zlib from 'zlib';
+import { COMPILE_DIRS, COMPILE_FILES } from '../config/compile.constants.js';
+// =============================================================================
+// MANIFEST LOADING
+// =============================================================================
+/**
+ * Load the compilation manifest from dist-v2/manifest.json.
+ *
+ * @param projectPath - Path to the project root (defaults to cwd)
+ * @returns The compilation manifest
+ * @throws Error if manifest not found or invalid
+ */
+export function loadManifest(projectPath = process.cwd()) {
+    const manifestPath = path.join(projectPath, COMPILE_DIRS.DIST_V2, COMPILE_FILES.MANIFEST_JSON);
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`Manifest not found at ${manifestPath}. ` +
+            `Run "lua compile" first to generate the compilation output.`);
+    }
+    try {
+        const content = fs.readFileSync(manifestPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse manifest: ${error.message}`);
+    }
+}
+/**
+ * Check if the compilation output exists.
+ *
+ * @param projectPath - Path to the project root
+ * @returns true if dist-v2/manifest.json exists
+ */
+export function hasCompilationOutput(projectPath = process.cwd()) {
+    const manifestPath = path.join(projectPath, COMPILE_DIRS.DIST_V2, COMPILE_FILES.MANIFEST_JSON);
+    return fs.existsSync(manifestPath);
+}
+// =============================================================================
+// ARTIFACT LOADING
+// =============================================================================
+/**
+ * Load a primitive artifact (bundled JS code) from disk.
+ *
+ * @param primitive - The primitive from the manifest
+ * @param projectPath - Path to the project root
+ * @returns The artifact code as a string
+ */
+export function loadArtifact(primitive, projectPath = process.cwd()) {
+    const artifactPath = path.join(projectPath, COMPILE_DIRS.DIST_V2, primitive.path);
+    if (!fs.existsSync(artifactPath)) {
+        throw new Error(`Artifact not found: ${artifactPath}`);
+    }
+    return fs.readFileSync(artifactPath, 'utf-8');
+}
+/**
+ * Load a primitive artifact and its metadata JSON.
+ *
+ * @param primitive - The primitive from the manifest
+ * @param projectPath - Path to the project root
+ * @returns Object with code and metadata
+ */
+export function loadArtifactWithMetadata(primitive, projectPath = process.cwd()) {
+    const code = loadArtifact(primitive, projectPath);
+    // Load metadata JSON (same name but .json extension)
+    const metadataPath = path.join(projectPath, COMPILE_DIRS.DIST_V2, path.join(path.dirname(primitive.path), path.basename(primitive.path, '.js') + '.json'));
+    let metadata = {};
+    if (fs.existsSync(metadataPath)) {
+        metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+    }
+    return { code, metadata };
+}
+/**
+ * Load source map for a primitive (if it exists).
+ *
+ * @param primitive - The primitive from the manifest
+ * @param projectPath - Path to the project root
+ * @returns The source map string or null if not found
+ */
+export function loadSourceMap(primitive, projectPath = process.cwd()) {
+    const sourceMapPath = path.join(projectPath, COMPILE_DIRS.DIST_V2, primitive.path + '.map');
+    if (!fs.existsSync(sourceMapPath)) {
+        return null;
+    }
+    return fs.readFileSync(sourceMapPath, 'utf-8');
+}
+// =============================================================================
+// COMPRESSION (for push)
+// =============================================================================
+/**
+ * Compress code for pushing to server.
+ * Uses gzip + base64 encoding (matches server expectation).
+ *
+ * @param code - The artifact code to compress
+ * @returns Base64-encoded gzipped code
+ */
+export function compressForPush(code) {
+    const compressed = zlib.gzipSync(Buffer.from(code, 'utf-8'));
+    return compressed.toString('base64');
+}
+/**
+ * Decompress code from server format.
+ *
+ * @param compressed - Base64-encoded gzipped code
+ * @returns The decompressed code
+ */
+export function decompressFromServer(compressed) {
+    const buffer = Buffer.from(compressed, 'base64');
+    const decompressed = zlib.gunzipSync(buffer);
+    return decompressed.toString('utf-8');
+}
+// =============================================================================
+// PRIMITIVE FILTERING
+// =============================================================================
+/**
+ * Get primitives of a specific kind from the manifest.
+ *
+ * @param manifest - The compilation manifest
+ * @param kind - The primitive kind to filter by
+ * @returns Array of primitives matching the kind
+ */
+export function getPrimitivesByKind(manifest, kind) {
+    return manifest.primitives.filter(p => p.kind === kind);
+}
+/**
+ * Find a primitive by name and kind.
+ *
+ * @param manifest - The compilation manifest
+ * @param name - The primitive name
+ * @param kind - Optional kind to filter by
+ * @returns The primitive or undefined
+ */
+export function findPrimitive(manifest, name, kind) {
+    return manifest.primitives.find(p => {
+        if (kind && p.kind !== kind)
+            return false;
+        return p.name === name;
+    });
+}
+// =============================================================================
+// AGENT INFO (from manifest)
+// =============================================================================
+/**
+ * Get the agent name from the compilation manifest.
+ *
+ * @param projectPath - Path to the project root (defaults to cwd)
+ * @returns The agent name, or null if not found or no manifest
+ */
+export function getAgentName(projectPath = process.cwd()) {
+    if (!hasCompilationOutput(projectPath))
+        return null;
+    return loadManifest(projectPath).agent?.name ?? null;
+}
+/**
+ * Get the agent persona from the compilation manifest.
+ *
+ * @param projectPath - Path to the project root (defaults to cwd)
+ * @returns The agent persona, or null if not found or no manifest
+ */
+export function getAgentPersona(projectPath = process.cwd()) {
+    if (!hasCompilationOutput(projectPath))
+        return null;
+    return loadManifest(projectPath).agent?.persona ?? null;
+}
+// =============================================================================
+// BATCH LOADING
+// =============================================================================
+/**
+ * Load all artifacts of a specific kind.
+ *
+ * @param manifest - The compilation manifest
+ * @param kind - The primitive kind
+ * @param projectPath - Path to the project root
+ * @returns Array of { primitive, code } objects
+ */
+export function loadAllArtifactsOfKind(manifest, kind, projectPath = process.cwd()) {
+    return getPrimitivesByKind(manifest, kind).map(primitive => ({
+        primitive,
+        code: loadArtifact(primitive, projectPath),
+    }));
+}
+//# sourceMappingURL=artifact-loader.js.map

package/dist/utils/artifact-loader.js.map

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

package/dist/utils/backup-helpers.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Backup Helper Utilities
+ *
+ * Utilities for project backup operations using S3 blob storage.
+ * Content is stored in S3, keyed by content hash for deduplication.
+ */
+import type { CompilationManifest, ProjectFile } from '../compiler/types.js';
+import type { BackupFileRef, BackupManifest, BlobUpload } from '../interfaces/backup.js';
+import type { YamlConfigBackup } from '../types/yaml.types.js';
+/**
+ * Calculate a hash for a string content.
+ *
+ * @param content - The content to hash
+ * @returns SHA-256 hash as hex string
+ */
+export declare function hashContent(content: string): string;
+/**
+ * Calculate combined project hash from all project files.
+ * This hash is used to detect if the project has changed since last backup.
+ *
+ * @param projectFiles - Array of project files from the manifest
+ * @returns Combined hash of all file hashes (sorted for determinism)
+ */
+export declare function calculateProjectHash(projectFiles: ProjectFile[]): string;
+/**
+ * Get the current project hash from the compilation manifest.
+ * Returns null if no manifest exists.
+ *
+ * @param projectPath - Path to the project root
+ * @returns The project hash or null
+ */
+export declare function getCurrentProjectHash(projectPath?: string): string | null;
+/**
+ * Load all project source files from dist-v2/sources/ directory.
+ *
+ * @param manifest - The compilation manifest
+ * @param projectPath - Path to the project root
+ * @returns Map of relative path -> file content
+ */
+export declare function loadProjectSources(manifest: CompilationManifest, projectPath?: string): Map<string, string>;
+/**
+ * Load source content by hash from dist-v2/sources/ directory.
+ *
+ * @param hash - The content hash
+ * @param relativePath - Original relative path (for extension)
+ * @param projectPath - Path to the project root
+ * @returns The file content or null if not found
+ */
+export declare function loadSourceByHash(hash: string, relativePath: string, projectPath?: string): string | null;
+/**
+ * Prepare file references (manifest entries) from the compilation output.
+ * No content included - just metadata for the manifest.
+ *
+ * @param projectPath - Path to the project root
+ * @returns Array of file references ready for manifest
+ */
+export declare function prepareFileRefs(projectPath?: string): BackupFileRef[];
+/**
+ * Prepare blobs for upload from the compilation output.
+ * Only prepares blobs for the specified hashes (missing ones).
+ *
+ * @param hashes - Array of hashes to prepare (typically the missing ones)
+ * @param manifest - The compilation manifest
+ * @param projectPath - Path to the project root
+ * @returns Array of blobs ready for upload (hash + base64 content)
+ */
+export declare function prepareBlobsForUpload(hashes: string[], manifest: CompilationManifest, projectPath?: string): BlobUpload[];
+/**
+ * Get all unique hashes from the manifest.
+ *
+ * @param projectPath - Path to the project root
+ * @returns Array of unique content hashes
+ */
+export declare function getAllFileHashes(projectPath?: string): string[];
+/**
+ * Download multiple blobs in parallel from presigned URLs.
+ *
+ * @param urls - Map of hash -> presigned URL
+ * @param concurrency - Maximum number of parallel downloads (default: 10)
+ * @returns Map of hash -> content buffer
+ */
+export declare function downloadBlobsParallel(urls: Record<string, string>, concurrency?: number): Promise<Map<string, Buffer>>;
+/**
+ * Restore project files from a backup manifest and downloaded blobs.
+ * Creates all directories and files in the target directory.
+ *
+ * @param manifest - The backup manifest (file references)
+ * @param blobs - Map of hash -> content buffer (downloaded blobs)
+ * @param targetDir - Target directory to restore to
+ * @param options - Optional settings
+ */
+export declare function restoreProjectFromBackup(manifest: BackupManifest, blobs: Map<string, Buffer>, targetDir: string, options?: {
+    overwrite?: boolean;
+}): void;
+/**
+ * Check which files would be created/overwritten by restore.
+ * Useful for showing user what will happen before restore.
+ *
+ * @param manifest - The backup manifest
+ * @param targetDir - Target directory to check against
+ * @returns Object with new files, existing files, and total count
+ */
+export declare function checkRestoreConflicts(manifest: BackupManifest, targetDir: string): {
+    newFiles: string[];
+    existingFiles: string[];
+    totalFiles: number;
+};
+/**
+ * Check if project backup is out of sync (local changes not pushed).
+ *
+ * @param currentHash - Current project hash from manifest
+ * @param tracking - Backup tracking from YAML
+ * @returns true if backup is out of sync
+ */
+export declare function isBackupOutOfSync(currentHash: string, tracking: YamlConfigBackup | undefined): boolean;
+/**
+ * Create backup tracking object after successful push.
+ *
+ * @param projectHash - The hash of the pushed backup
+ * @returns YamlConfigBackup object for storing in YAML
+ */
+export declare function createBackupTracking(projectHash: string): YamlConfigBackup;