skedyul 0.1.9 → 0.1.10

package/dist/cli/commands/diff.d.ts

@@ -0,0 +1 @@
+export declare function diffCommand(args: string[]): Promise<void>;

package/dist/cli/commands/diff.js

@@ -0,0 +1,295 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffCommand = diffCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const utils_1 = require("../utils");
+const config_1 = require("../../config");
+function printHelp() {
+    console.log(`
+skedyul dev diff - Show what would change on deploy
+
+Usage:
+  skedyul dev diff [options]
+
+Options:
+  --config, -c        Path to config file (default: auto-detect skedyul.config.ts)
+  --registry, -r      Path to registry file to compare tools
+  --json              Output as JSON
+  --help, -h          Show this help message
+
+Description:
+  Compares your local skedyul.config.ts with the currently deployed configuration.
+  Shows changes in environment variables, tools, and workflows that would be
+  applied when deploying a new version.
+
+Examples:
+  # Show diff for config in current directory
+  skedyul dev diff
+
+  # Show diff with specific config
+  skedyul dev diff --config ./skedyul.config.ts
+
+  # Compare against specific registry
+  skedyul dev diff --registry ./dist/registry.js
+`);
+}
+function findConfigFile(startDir) {
+    for (const fileName of config_1.CONFIG_FILE_NAMES) {
+        const filePath = path.join(startDir, fileName);
+        if (fs.existsSync(filePath)) {
+            return filePath;
+        }
+    }
+    return null;
+}
+function compareEnvSchemas(newEnv, oldEnv) {
+    const newKeys = newEnv ? Object.keys(newEnv) : [];
+    const oldKeys = oldEnv ? Object.keys(oldEnv) : [];
+    const added = newKeys.filter((k) => !oldKeys.includes(k));
+    const removed = oldKeys.filter((k) => !newKeys.includes(k));
+    const changed = [];
+    // Check for changes in existing keys
+    for (const key of newKeys) {
+        if (oldKeys.includes(key)) {
+            const newDef = newEnv?.[key];
+            const oldDef = oldEnv?.[key];
+            const changes = [];
+            if (newDef?.required !== oldDef?.required) {
+                changes.push(newDef?.required
+                    ? 'now required'
+                    : 'no longer required');
+            }
+            if (newDef?.visibility !== oldDef?.visibility) {
+                changes.push(`visibility: ${oldDef?.visibility || 'visible'} → ${newDef?.visibility || 'visible'}`);
+            }
+            if (newDef?.label !== oldDef?.label) {
+                changes.push(`label changed`);
+            }
+            if (changes.length > 0) {
+                changed.push({ key, changes });
+            }
+        }
+    }
+    return { added, removed, changed };
+}
+async function diffCommand(args) {
+    const { flags } = (0, utils_1.parseArgs)(args);
+    if (flags.help || flags.h) {
+        printHelp();
+        return;
+    }
+    const jsonOutput = Boolean(flags.json);
+    // Find config file
+    let configPath = (flags.config || flags.c);
+    if (!configPath) {
+        const foundConfig = findConfigFile(process.cwd());
+        if (!foundConfig) {
+            if (jsonOutput) {
+                console.log(JSON.stringify({ error: 'No config file found' }));
+            }
+            else {
+                console.error('❌ No config file found');
+                console.error(`   Create one of: ${config_1.CONFIG_FILE_NAMES.join(', ')}`);
+            }
+            process.exit(1);
+        }
+        configPath = foundConfig;
+    }
+    else {
+        configPath = path.resolve(process.cwd(), configPath);
+    }
+    if (!fs.existsSync(configPath)) {
+        if (jsonOutput) {
+            console.log(JSON.stringify({ error: `Config file not found: ${configPath}` }));
+        }
+        else {
+            console.error(`❌ Config file not found: ${configPath}`);
+        }
+        process.exit(1);
+    }
+    // Load config
+    let config;
+    try {
+        config = await (0, config_1.loadConfig)(configPath);
+    }
+    catch (error) {
+        if (jsonOutput) {
+            console.log(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+        }
+        else {
+            console.error(`❌ Failed to load config: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        process.exit(1);
+    }
+    // Validate config
+    const validation = (0, config_1.validateConfig)(config);
+    if (!validation.valid) {
+        if (jsonOutput) {
+            console.log(JSON.stringify({ error: 'Invalid config', errors: validation.errors }));
+        }
+        else {
+            console.error('❌ Config validation failed:');
+            for (const err of validation.errors) {
+                console.error(`   • ${err}`);
+            }
+        }
+        process.exit(1);
+    }
+    // For now, we compare against "no previous config" (new deploy scenario)
+    // In a full implementation, this would fetch the current deployed config from the server
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const previousConfig = undefined;
+    // Compare env schemas
+    const globalEnvDiff = compareEnvSchemas(config.env, previousConfig?.env);
+    const installEnvDiff = compareEnvSchemas(config.install?.env, previousConfig?.install?.env);
+    // Compare tools if registry path provided
+    let toolsDiff;
+    const registryPath = (flags.registry || flags.r);
+    if (registryPath) {
+        try {
+            const registry = await (0, utils_1.loadRegistry)(path.resolve(process.cwd(), registryPath));
+            const toolNames = Object.values(registry).map((t) => t.name);
+            // For now, show all tools as "added" since we don't have previous state
+            toolsDiff = {
+                added: toolNames,
+                removed: [],
+                total: toolNames.length,
+            };
+        }
+        catch (error) {
+            // Ignore registry loading errors for diff
+        }
+    }
+    const result = {
+        configPath,
+        globalEnv: globalEnvDiff,
+        installEnv: installEnvDiff,
+        tools: toolsDiff,
+        summary: {
+            hasChanges: globalEnvDiff.added.length > 0 ||
+                globalEnvDiff.removed.length > 0 ||
+                globalEnvDiff.changed.length > 0 ||
+                installEnvDiff.added.length > 0 ||
+                installEnvDiff.removed.length > 0 ||
+                installEnvDiff.changed.length > 0 ||
+                (toolsDiff?.added.length ?? 0) > 0 ||
+                (toolsDiff?.removed.length ?? 0) > 0,
+            globalEnvChanges: globalEnvDiff.added.length +
+                globalEnvDiff.removed.length +
+                globalEnvDiff.changed.length,
+            installEnvChanges: installEnvDiff.added.length +
+                installEnvDiff.removed.length +
+                installEnvDiff.changed.length,
+            toolChanges: (toolsDiff?.added.length ?? 0) + (toolsDiff?.removed.length ?? 0),
+        },
+    };
+    if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // Human-readable output
+    console.log('');
+    console.log(`📦 ${config.name}${config.version ? ` v${config.version}` : ''}`);
+    console.log(`   ${configPath}`);
+    console.log('');
+    // Note about comparison
+    if (previousConfig === undefined) {
+        console.log('ℹ️  Comparing against empty state (new deployment)');
+        console.log('');
+    }
+    // Global env diff
+    if (result.summary.globalEnvChanges > 0) {
+        console.log('Global Environment Variables:');
+        for (const key of globalEnvDiff.added) {
+            const def = config.env?.[key];
+            const required = def?.required ? ' (required)' : '';
+            console.log(`  + ${key}${required}`);
+        }
+        for (const key of globalEnvDiff.removed) {
+            console.log(`  - ${key}`);
+        }
+        for (const item of globalEnvDiff.changed) {
+            console.log(`  ~ ${item.key}: ${item.changes.join(', ')}`);
+        }
+        console.log('');
+    }
+    // Install env diff
+    if (result.summary.installEnvChanges > 0) {
+        console.log('Install Environment Variables:');
+        for (const key of installEnvDiff.added) {
+            const def = config.install?.env?.[key];
+            const required = def?.required ? ' (required)' : '';
+            console.log(`  + ${key}${required}`);
+        }
+        for (const key of installEnvDiff.removed) {
+            console.log(`  - ${key}`);
+        }
+        for (const item of installEnvDiff.changed) {
+            console.log(`  ~ ${item.key}: ${item.changes.join(', ')}`);
+        }
+        console.log('');
+    }
+    // Tools diff
+    if (toolsDiff && result.summary.toolChanges > 0) {
+        console.log('Tools:');
+        for (const name of toolsDiff.added) {
+            console.log(`  + ${name}`);
+        }
+        for (const name of toolsDiff.removed) {
+            console.log(`  - ${name}`);
+        }
+        console.log('');
+    }
+    // Summary
+    if (result.summary.hasChanges) {
+        console.log('Summary:');
+        if (result.summary.globalEnvChanges > 0) {
+            console.log(`  • ${result.summary.globalEnvChanges} global env var change(s)`);
+        }
+        if (result.summary.installEnvChanges > 0) {
+            console.log(`  • ${result.summary.installEnvChanges} install env var change(s)`);
+        }
+        if (result.summary.toolChanges > 0) {
+            console.log(`  • ${result.summary.toolChanges} tool change(s)`);
+        }
+        console.log('');
+        console.log('✅ Ready to deploy');
+    }
+    else {
+        console.log('✅ No changes detected');
+    }
+}

package/dist/cli/commands/invoke.js

@@ -198,7 +198,6 @@ async function invokeCommand(args) {
     if (estimateMode) {
         console.error('Mode: estimate (billing only)');
     }
-    console.error('');
     try {
         const handler = tool.handler;
         const result = await handler({

package/dist/cli/commands/validate.d.ts

@@ -0,0 +1 @@
+export declare function validateCommand(args: string[]): Promise<void>;

package/dist/cli/commands/validate.js

@@ -0,0 +1,269 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateCommand = validateCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const utils_1 = require("../utils");
+const config_1 = require("../../config");
+function printHelp() {
+    console.log(`
+skedyul dev validate - Validate skedyul.config.ts
+
+Usage:
+  skedyul dev validate [options]
+
+Options:
+  --config, -c        Path to config file (default: auto-detect skedyul.config.ts)
+  --verbose, -v       Show detailed validation output
+  --json              Output as JSON
+  --help, -h          Show this help message
+
+Examples:
+  # Validate config in current directory
+  skedyul dev validate
+
+  # Validate specific config file
+  skedyul dev validate --config ./skedyul.config.ts
+
+  # Verbose output
+  skedyul dev validate --verbose
+`);
+}
+function findConfigFile(startDir) {
+    for (const fileName of config_1.CONFIG_FILE_NAMES) {
+        const filePath = path.join(startDir, fileName);
+        if (fs.existsSync(filePath)) {
+            return filePath;
+        }
+    }
+    return null;
+}
+async function validateCommand(args) {
+    const { flags } = (0, utils_1.parseArgs)(args);
+    if (flags.help || flags.h) {
+        printHelp();
+        return;
+    }
+    const verbose = Boolean(flags.verbose || flags.v);
+    const jsonOutput = Boolean(flags.json);
+    // Find config file
+    let configPath = (flags.config || flags.c);
+    if (!configPath) {
+        const foundConfig = findConfigFile(process.cwd());
+        if (!foundConfig) {
+            const result = {
+                valid: false,
+                configPath: '',
+                errors: [`No config file found. Create one of: ${config_1.CONFIG_FILE_NAMES.join(', ')}`],
+                warnings: [],
+            };
+            if (jsonOutput) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.error('❌ No config file found');
+                console.error(`   Create one of: ${config_1.CONFIG_FILE_NAMES.join(', ')}`);
+            }
+            process.exit(1);
+        }
+        configPath = foundConfig;
+    }
+    else {
+        configPath = path.resolve(process.cwd(), configPath);
+    }
+    if (!fs.existsSync(configPath)) {
+        const result = {
+            valid: false,
+            configPath,
+            errors: [`Config file not found: ${configPath}`],
+            warnings: [],
+        };
+        if (jsonOutput) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.error(`❌ Config file not found: ${configPath}`);
+        }
+        process.exit(1);
+    }
+    // Load and validate config
+    const warnings = [];
+    let config;
+    try {
+        config = await (0, config_1.loadConfig)(configPath);
+    }
+    catch (error) {
+        const result = {
+            valid: false,
+            configPath,
+            errors: [error instanceof Error ? error.message : String(error)],
+            warnings: [],
+        };
+        if (jsonOutput) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.error(`❌ Failed to load config: ${result.errors[0]}`);
+        }
+        process.exit(1);
+    }
+    // Validate schema
+    const validation = (0, config_1.validateConfig)(config);
+    // Check for common issues (warnings)
+    if (!config.computeLayer) {
+        warnings.push('No computeLayer specified. Will default to "dedicated".');
+    }
+    if (!config.tools) {
+        warnings.push('No tools path specified. Will default to "./src/registry.ts".');
+    }
+    if (!config.workflows) {
+        warnings.push('No workflows path specified. Will default to "./workflows".');
+    }
+    // Check if tools file exists
+    const toolsPath = config.tools || './src/registry.ts';
+    const absoluteToolsPath = path.resolve(path.dirname(configPath), toolsPath);
+    if (!fs.existsSync(absoluteToolsPath)) {
+        // Check for .js variant
+        const jsToolsPath = absoluteToolsPath.replace(/\.ts$/, '.js');
+        if (!fs.existsSync(jsToolsPath)) {
+            warnings.push(`Tools file not found: ${toolsPath}`);
+        }
+    }
+    // Check if workflows directory exists
+    const workflowsPath = config.workflows || './workflows';
+    const absoluteWorkflowsPath = path.resolve(path.dirname(configPath), workflowsPath);
+    if (!fs.existsSync(absoluteWorkflowsPath)) {
+        warnings.push(`Workflows directory not found: ${workflowsPath}`);
+    }
+    const envKeys = (0, config_1.getAllEnvKeys)(config);
+    const requiredInstallKeys = (0, config_1.getRequiredInstallEnvKeys)(config);
+    const result = {
+        valid: validation.valid,
+        configPath,
+        config: {
+            name: config.name,
+            version: config.version,
+            computeLayer: config.computeLayer,
+            runtime: config.runtime,
+            tools: config.tools,
+            workflows: config.workflows,
+            globalEnvKeys: envKeys.global,
+            installEnvKeys: envKeys.install,
+            requiredInstallEnvKeys: requiredInstallKeys,
+            appModels: config.install?.appModels?.map((m) => m.entityHandle) || [],
+        },
+        errors: validation.errors,
+        warnings,
+    };
+    if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(validation.valid ? 0 : 1);
+    }
+    // Human-readable output
+    console.log('');
+    console.log(`📦 ${config.name}${config.version ? ` v${config.version}` : ''}`);
+    console.log(`   ${configPath}`);
+    console.log('');
+    if (verbose) {
+        console.log('Configuration:');
+        console.log(`  Compute Layer: ${config.computeLayer || 'dedicated (default)'}`);
+        console.log(`  Runtime:       ${config.runtime || 'node-22 (default)'}`);
+        console.log(`  Tools:         ${config.tools || './src/registry.ts (default)'}`);
+        console.log(`  Workflows:     ${config.workflows || './workflows (default)'}`);
+        console.log('');
+        if (envKeys.global.length > 0) {
+            console.log('Global Environment Variables:');
+            for (const key of envKeys.global) {
+                const def = config.env?.[key];
+                const required = def?.required ? ' (required)' : '';
+                const visibility = def?.visibility === 'encrypted' ? ' 🔒' : '';
+                console.log(`  ${key}${required}${visibility}`);
+                if (def?.label)
+                    console.log(`    └─ ${def.label}`);
+            }
+            console.log('');
+        }
+        if (envKeys.install.length > 0) {
+            console.log('Install Environment Variables:');
+            for (const key of envKeys.install) {
+                const def = config.install?.env?.[key];
+                const required = def?.required ? ' (required)' : '';
+                const visibility = def?.visibility === 'encrypted' ? ' 🔒' : '';
+                console.log(`  ${key}${required}${visibility}`);
+                if (def?.label)
+                    console.log(`    └─ ${def.label}`);
+            }
+            console.log('');
+        }
+        if (config.install?.appModels && config.install.appModels.length > 0) {
+            console.log('App Models:');
+            for (const model of config.install.appModels) {
+                console.log(`  ${model.entityHandle}: ${model.label}`);
+            }
+            console.log('');
+        }
+    }
+    // Show errors
+    if (validation.errors.length > 0) {
+        console.log('❌ Validation Errors:');
+        for (const error of validation.errors) {
+            console.log(`   • ${error}`);
+        }
+        console.log('');
+    }
+    // Show warnings
+    if (warnings.length > 0) {
+        console.log('⚠️  Warnings:');
+        for (const warning of warnings) {
+            console.log(`   • ${warning}`);
+        }
+        console.log('');
+    }
+    // Final status
+    if (validation.valid) {
+        console.log('✅ Config is valid');
+        if (!verbose) {
+            console.log(`   ${envKeys.global.length} global env vars, ${envKeys.install.length} install env vars`);
+            if (requiredInstallKeys.length > 0) {
+                console.log(`   ${requiredInstallKeys.length} required install vars: ${requiredInstallKeys.join(', ')}`);
+            }
+        }
+    }
+    else {
+        console.log('❌ Config has errors');
+        process.exit(1);
+    }
+}

package/dist/cli/index.js

@@ -4,6 +4,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const invoke_1 = require("./commands/invoke");
 const tools_1 = require("./commands/tools");
 const serve_1 = require("./commands/serve");
+const validate_1 = require("./commands/validate");
+const diff_1 = require("./commands/diff");
 const args = process.argv.slice(2);
 function printUsage() {
     console.log(`
@@ -16,6 +18,8 @@ Commands:
   dev invoke <tool>   Invoke a tool from the registry
   dev tools           List all tools in the registry
   dev serve           Start a local MCP server
+  dev validate        Validate skedyul.config.ts
+  dev diff            Show what would change on deploy
 
 Run 'skedyul dev <command> --help' for more information on a command.
 `);
@@ -31,11 +35,15 @@ Commands:
   invoke <tool>   Invoke a tool from the registry
   tools           List all tools in the registry
   serve           Start a local MCP server
+  validate        Validate skedyul.config.ts
+  diff            Show what would change on deploy
 
 Examples:
   skedyul dev invoke my_tool --registry ./dist/registry.js --args '{"key": "value"}'
   skedyul dev tools --registry ./dist/registry.js
   skedyul dev serve --registry ./dist/registry.js --port 3001
+  skedyul dev validate
+  skedyul dev diff
 
 Options:
   --help, -h      Show help for a command
@@ -68,6 +76,12 @@ async function main() {
         case 'serve':
             await (0, serve_1.serveCommand)(subArgs);
             break;
+        case 'validate':
+            await (0, validate_1.validateCommand)(subArgs);
+            break;
+        case 'diff':
+            await (0, diff_1.diffCommand)(subArgs);
+            break;
         default:
             console.error(`Unknown dev command: ${subCommand}`);
             console.error(`Run 'skedyul dev --help' for usage information.`);

package/dist/config.d.ts

@@ -0,0 +1,116 @@
+export type EnvVisibility = 'visible' | 'encrypted';
+export interface EnvVariableDefinition {
+    /** Human-readable label for the variable */
+    label: string;
+    /** Whether this variable is required */
+    required?: boolean;
+    /** Visibility setting (encrypted values are hidden in UI) */
+    visibility?: EnvVisibility;
+    /** Default value if not provided */
+    default?: string;
+    /** Description/help text */
+    description?: string;
+    /** Placeholder text for input fields */
+    placeholder?: string;
+}
+export type EnvSchema = Record<string, EnvVariableDefinition>;
+export interface AppModelDefinition {
+    /** Unique handle for the entity (e.g., 'client', 'patient') */
+    entityHandle: string;
+    /** Human-readable label */
+    label: string;
+    /** Description of what this model represents */
+    description?: string;
+}
+export interface InstallConfig {
+    /**
+     * Per-install environment variables.
+     * These are configured by the user when installing the app.
+     * Values are stored per-installation and can differ between installs.
+     */
+    env?: EnvSchema;
+    /**
+     * Model mappings required for this app.
+     * Users will map these to their CRM models during installation.
+     */
+    appModels?: AppModelDefinition[];
+}
+export type ComputeLayerType = 'serverless' | 'dedicated';
+export type RuntimeType = 'node-22' | 'node-20' | 'node-18';
+export interface SkedyulConfig {
+    /** App name */
+    name: string;
+    /** App version (semver) */
+    version?: string;
+    /** App description */
+    description?: string;
+    /** Compute layer: 'serverless' (Lambda) or 'dedicated' (ECS/Docker) */
+    computeLayer?: ComputeLayerType;
+    /** Runtime environment */
+    runtime?: RuntimeType;
+    /** Path to the tool registry file (default: './src/registry.ts') */
+    tools?: string;
+    /** Path to the workflows directory (default: './workflows') */
+    workflows?: string;
+    /**
+     * Global/version-level environment variables.
+     * These are baked into the container and are the same for all installations.
+     * Use for configuration that doesn't change per-install.
+     */
+    env?: EnvSchema;
+    /**
+     * Install-time configuration.
+     * Defines what users need to configure when installing the app.
+     */
+    install?: InstallConfig;
+}
+/**
+ * Define a Skedyul app configuration with full type safety.
+ *
+ * @example
+ * ```typescript
+ * // skedyul.config.ts
+ * import { defineConfig } from 'skedyul'
+ *
+ * export default defineConfig({
+ *   name: 'My App',
+ *   computeLayer: 'dedicated',
+ *   tools: './src/registry.ts',
+ *   env: {
+ *     LOG_LEVEL: { label: 'Log Level', default: 'info' },
+ *   },
+ *   install: {
+ *     env: {
+ *       API_KEY: { label: 'API Key', required: true, visibility: 'encrypted' },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare function defineConfig(config: SkedyulConfig): SkedyulConfig;
+/**
+ * Default config file names to search for
+ */
+export declare const CONFIG_FILE_NAMES: string[];
+/**
+ * Load a Skedyul config from a file path
+ */
+export declare function loadConfig(configPath: string): Promise<SkedyulConfig>;
+/**
+ * Validate a config object
+ */
+export declare function validateConfig(config: SkedyulConfig): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Get all required install env keys from a config
+ */
+export declare function getRequiredInstallEnvKeys(config: SkedyulConfig): string[];
+/**
+ * Get all env keys (both global and install) from a config
+ */
+export declare function getAllEnvKeys(config: SkedyulConfig): {
+    global: string[];
+    install: string[];
+};

package/dist/config.js

@@ -0,0 +1,233 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_FILE_NAMES = void 0;
+exports.defineConfig = defineConfig;
+exports.loadConfig = loadConfig;
+exports.validateConfig = validateConfig;
+exports.getRequiredInstallEnvKeys = getRequiredInstallEnvKeys;
+exports.getAllEnvKeys = getAllEnvKeys;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// ─────────────────────────────────────────────────────────────────────────────
+// Helper Function
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Define a Skedyul app configuration with full type safety.
+ *
+ * @example
+ * ```typescript
+ * // skedyul.config.ts
+ * import { defineConfig } from 'skedyul'
+ *
+ * export default defineConfig({
+ *   name: 'My App',
+ *   computeLayer: 'dedicated',
+ *   tools: './src/registry.ts',
+ *   env: {
+ *     LOG_LEVEL: { label: 'Log Level', default: 'info' },
+ *   },
+ *   install: {
+ *     env: {
+ *       API_KEY: { label: 'API Key', required: true, visibility: 'encrypted' },
+ *     },
+ *   },
+ * })
+ * ```
+ */
+function defineConfig(config) {
+    return config;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Config Loading Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Default config file names to search for
+ */
+exports.CONFIG_FILE_NAMES = [
+    'skedyul.config.ts',
+    'skedyul.config.js',
+    'skedyul.config.mjs',
+    'skedyul.config.cjs',
+];
+/**
+ * Transpile a TypeScript config file to JavaScript
+ */
+async function transpileTypeScript(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    // Simple transpilation: remove type annotations and convert to CommonJS
+    // For more complex configs, users should pre-compile or use a JS config
+    let transpiled = content
+        // Remove import type statements
+        .replace(/import\s+type\s+\{[^}]+\}\s+from\s+['"][^'"]+['"]\s*;?\n?/g, '')
+        // Convert import { defineConfig } from 'skedyul' to require
+        .replace(/import\s+\{\s*defineConfig\s*\}\s+from\s+['"]skedyul['"]\s*;?\n?/g, '')
+        // Remove type annotations like : SkedyulConfig
+        .replace(/:\s*SkedyulConfig/g, '')
+        // Convert export default to module.exports
+        .replace(/export\s+default\s+/, 'module.exports = ')
+        // Replace defineConfig() wrapper with just the object
+        .replace(/defineConfig\s*\(\s*\{/, '{')
+        // Remove the closing paren from defineConfig
+        .replace(/\}\s*\)\s*;?\s*$/, '}');
+    return transpiled;
+}
+/**
+ * Load a Skedyul config from a file path
+ */
+async function loadConfig(configPath) {
+    const absolutePath = path.resolve(configPath);
+    if (!fs.existsSync(absolutePath)) {
+        throw new Error(`Config file not found: ${absolutePath}`);
+    }
+    const isTypeScript = absolutePath.endsWith('.ts');
+    try {
+        let moduleToLoad = absolutePath;
+        if (isTypeScript) {
+            // Transpile TypeScript to a temp JS file
+            const transpiled = await transpileTypeScript(absolutePath);
+            const tempDir = os.tmpdir();
+            const tempFile = path.join(tempDir, `skedyul-config-${Date.now()}.js`);
+            fs.writeFileSync(tempFile, transpiled);
+            moduleToLoad = tempFile;
+            try {
+                const module = require(moduleToLoad);
+                const config = module.default || module;
+                if (!config || typeof config !== 'object') {
+                    throw new Error('Config file must export a configuration object');
+                }
+                if (!config.name || typeof config.name !== 'string') {
+                    throw new Error('Config must have a "name" property');
+                }
+                return config;
+            }
+            finally {
+                // Clean up temp file
+                try {
+                    fs.unlinkSync(tempFile);
+                }
+                catch {
+                    // Ignore cleanup errors
+                }
+            }
+        }
+        // For JS files, use dynamic import
+        const module = await Promise.resolve(`${moduleToLoad}`).then(s => __importStar(require(s)));
+        const config = module.default || module;
+        if (!config || typeof config !== 'object') {
+            throw new Error('Config file must export a configuration object');
+        }
+        if (!config.name || typeof config.name !== 'string') {
+            throw new Error('Config must have a "name" property');
+        }
+        return config;
+    }
+    catch (error) {
+        throw new Error(`Failed to load config from ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Validate a config object
+ */
+function validateConfig(config) {
+    const errors = [];
+    // Required fields
+    if (!config.name) {
+        errors.push('Missing required field: name');
+    }
+    // Validate computeLayer
+    if (config.computeLayer && !['serverless', 'dedicated'].includes(config.computeLayer)) {
+        errors.push(`Invalid computeLayer: ${config.computeLayer}. Must be 'serverless' or 'dedicated'`);
+    }
+    // Validate runtime
+    if (config.runtime && !['node-22', 'node-20', 'node-18'].includes(config.runtime)) {
+        errors.push(`Invalid runtime: ${config.runtime}. Must be 'node-22', 'node-20', or 'node-18'`);
+    }
+    // Validate env schema
+    if (config.env) {
+        for (const [key, def] of Object.entries(config.env)) {
+            if (!def.label) {
+                errors.push(`env.${key}: Missing required field 'label'`);
+            }
+            if (def.visibility && !['visible', 'encrypted'].includes(def.visibility)) {
+                errors.push(`env.${key}: Invalid visibility '${def.visibility}'`);
+            }
+        }
+    }
+    // Validate install.env schema
+    if (config.install?.env) {
+        for (const [key, def] of Object.entries(config.install.env)) {
+            if (!def.label) {
+                errors.push(`install.env.${key}: Missing required field 'label'`);
+            }
+            if (def.visibility && !['visible', 'encrypted'].includes(def.visibility)) {
+                errors.push(`install.env.${key}: Invalid visibility '${def.visibility}'`);
+            }
+        }
+    }
+    // Validate appModels
+    if (config.install?.appModels) {
+        for (let i = 0; i < config.install.appModels.length; i++) {
+            const model = config.install.appModels[i];
+            if (!model.entityHandle) {
+                errors.push(`install.appModels[${i}]: Missing required field 'entityHandle'`);
+            }
+            if (!model.label) {
+                errors.push(`install.appModels[${i}]: Missing required field 'label'`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Get all required install env keys from a config
+ */
+function getRequiredInstallEnvKeys(config) {
+    if (!config.install?.env)
+        return [];
+    return Object.entries(config.install.env)
+        .filter(([, def]) => def.required)
+        .map(([key]) => key);
+}
+/**
+ * Get all env keys (both global and install) from a config
+ */
+function getAllEnvKeys(config) {
+    return {
+        global: config.env ? Object.keys(config.env) : [],
+        install: config.install?.env ? Object.keys(config.install.env) : [],
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export * from './types';
 export { server } from './server';
 export { workplace, communicationChannel } from './core/client';
+export { defineConfig, loadConfig, validateConfig, getRequiredInstallEnvKeys, getAllEnvKeys, CONFIG_FILE_NAMES, } from './config';
+export type { SkedyulConfig, EnvVariableDefinition, EnvSchema, EnvVisibility, InstallConfig, AppModelDefinition, ComputeLayerType, RuntimeType, } from './config';

package/dist/index.js

@@ -14,10 +14,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.communicationChannel = exports.workplace = exports.server = void 0;
+exports.CONFIG_FILE_NAMES = exports.getAllEnvKeys = exports.getRequiredInstallEnvKeys = exports.validateConfig = exports.loadConfig = exports.defineConfig = exports.communicationChannel = exports.workplace = exports.server = void 0;
 __exportStar(require("./types"), exports);
 var server_1 = require("./server");
 Object.defineProperty(exports, "server", { enumerable: true, get: function () { return server_1.server; } });
 var client_1 = require("./core/client");
 Object.defineProperty(exports, "workplace", { enumerable: true, get: function () { return client_1.workplace; } });
 Object.defineProperty(exports, "communicationChannel", { enumerable: true, get: function () { return client_1.communicationChannel; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
+Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return config_1.validateConfig; } });
+Object.defineProperty(exports, "getRequiredInstallEnvKeys", { enumerable: true, get: function () { return config_1.getRequiredInstallEnvKeys; } });
+Object.defineProperty(exports, "getAllEnvKeys", { enumerable: true, get: function () { return config_1.getAllEnvKeys; } });
+Object.defineProperty(exports, "CONFIG_FILE_NAMES", { enumerable: true, get: function () { return config_1.CONFIG_FILE_NAMES; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skedyul",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "The Skedyul SDK for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",