genbox 1.0.12 → 1.0.13

package/dist/config-explainer.js

@@ -0,0 +1,379 @@
+"use strict";
+/**
+ * Config Explainer
+ *
+ * Traces where each configuration value comes from through the resolution hierarchy:
+ * 1. CLI flags (highest priority)
+ * 2. Profile overrides
+ * 3. Project config (genbox.yaml explicit values)
+ * 4. Workspace config
+ * 5. Detected values (from scanner)
+ * 6. Schema defaults (lowest priority)
+ *
+ * Also identifies values that were auto-detected vs explicitly configured.
+ */
+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.ConfigExplainer = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
+// Schema defaults for known fields
+const SCHEMA_DEFAULTS = {
+    'defaults.size': 'medium',
+    'defaults.branch': 'main',
+    'defaults.database.mode': 'local',
+};
+// Fields that support $detect markers (in v4)
+const DETECTABLE_FIELDS = [
+    'apps.*.port',
+    'apps.*.type',
+    'apps.*.framework',
+    'apps.*.commands.install',
+    'apps.*.commands.dev',
+    'apps.*.commands.build',
+    'apps.*.commands.start',
+];
+class ConfigExplainer {
+    loadResult;
+    detectedConfig = null;
+    cliOverrides = {};
+    constructor(loadResult) {
+        this.loadResult = loadResult;
+        this.loadDetectedConfig();
+    }
+    /**
+     * Set CLI overrides for explanation
+     */
+    setCliOverrides(overrides) {
+        this.cliOverrides = overrides;
+    }
+    /**
+     * Load detected configuration if available
+     */
+    loadDetectedConfig() {
+        const detectedPath = path.join(this.loadResult.root, '.genbox', 'detected.yaml');
+        if (fs.existsSync(detectedPath)) {
+            try {
+                const content = fs.readFileSync(detectedPath, 'utf8');
+                this.detectedConfig = yaml.load(content);
+            }
+            catch {
+                // Ignore parse errors
+            }
+        }
+    }
+    /**
+     * Explain where a configuration value comes from
+     */
+    explain(configPath, profileName) {
+        const sources = [];
+        // 1. Check CLI overrides
+        const cliValue = this.getNestedValue(this.cliOverrides, configPath);
+        if (cliValue !== undefined) {
+            sources.push({
+                source: 'cli',
+                value: cliValue,
+                used: true,
+                explicit: true,
+            });
+        }
+        // 2. Check profile overrides
+        if (profileName && this.loadResult.config?.profiles?.[profileName]) {
+            const profile = this.loadResult.config.profiles[profileName];
+            const profileValue = this.getProfileValue(profile, configPath);
+            if (profileValue !== undefined) {
+                sources.push({
+                    source: 'profile',
+                    value: profileValue,
+                    used: sources.length === 0,
+                    profileName,
+                    explicit: true,
+                });
+            }
+        }
+        // 3. Check project config (explicit values)
+        const projectSource = this.loadResult.sources.find(s => s.type === 'project');
+        if (projectSource) {
+            const projectValue = this.getNestedValue(projectSource.config, configPath);
+            if (projectValue !== undefined) {
+                const isDetectMarker = projectValue === '$detect';
+                sources.push({
+                    source: 'project',
+                    value: projectValue,
+                    used: sources.length === 0 && !isDetectMarker,
+                    filePath: projectSource.path,
+                    explicit: !isDetectMarker,
+                });
+                // If it's a $detect marker, add the detected value
+                if (isDetectMarker) {
+                    const detected = this.getDetectedValue(configPath);
+                    if (detected) {
+                        sources.push({
+                            source: 'detected',
+                            value: detected.value,
+                            used: sources.length === 1, // Used if project has $detect
+                            detectedFrom: detected.source,
+                            explicit: false,
+                        });
+                    }
+                }
+            }
+        }
+        // 4. Check workspace config
+        const workspaceSource = this.loadResult.sources.find(s => s.type === 'workspace');
+        if (workspaceSource) {
+            const workspaceValue = this.getNestedValue(workspaceSource.config, configPath);
+            if (workspaceValue !== undefined) {
+                sources.push({
+                    source: 'workspace',
+                    value: workspaceValue,
+                    used: sources.length === 0,
+                    filePath: workspaceSource.path,
+                    explicit: true,
+                });
+            }
+        }
+        // 5. Check if value was inferred/detected (for apps without explicit values)
+        if (sources.length === 0 || sources.every(s => !s.used)) {
+            const inferred = this.getInferredValue(configPath);
+            if (inferred !== undefined) {
+                sources.push({
+                    source: 'inferred',
+                    value: inferred.value,
+                    used: sources.length === 0,
+                    detectedFrom: inferred.source,
+                    explicit: false,
+                });
+            }
+        }
+        // 6. Check schema defaults
+        const defaultValue = SCHEMA_DEFAULTS[configPath];
+        if (defaultValue !== undefined) {
+            sources.push({
+                source: 'default',
+                value: defaultValue,
+                used: sources.length === 0,
+                explicit: false,
+            });
+        }
+        return sources;
+    }
+    /**
+     * Get all detection warnings
+     */
+    getDetectionWarnings() {
+        const warnings = [];
+        const config = this.loadResult.config;
+        if (!config)
+            return warnings;
+        // Check each app for implicit type/port/framework
+        for (const [appName, appConfig] of Object.entries(config.apps || {})) {
+            // Check type - was it inferred?
+            if (appConfig.type) {
+                const typeExplanation = this.explain(`apps.${appName}.type`);
+                const typeSource = typeExplanation.find(s => s.used);
+                if (typeSource && !typeSource.explicit) {
+                    warnings.push(`App '${appName}' type '${appConfig.type}' was inferred from ${typeSource.detectedFrom || 'naming conventions'}. ` +
+                        `Add explicit 'type: ${appConfig.type}' to silence this warning.`);
+                }
+            }
+            // Check port - was it extracted via regex?
+            if (appConfig.port) {
+                const portExplanation = this.explain(`apps.${appName}.port`);
+                const portSource = portExplanation.find(s => s.used);
+                if (portSource && !portSource.explicit) {
+                    warnings.push(`App '${appName}' port ${appConfig.port} was extracted from ${portSource.detectedFrom || 'npm scripts'}. ` +
+                        `Add explicit 'port: ${appConfig.port}' to ensure consistent behavior.`);
+                }
+            }
+            // Check framework - was it detected?
+            if (appConfig.framework) {
+                const frameworkExplanation = this.explain(`apps.${appName}.framework`);
+                const frameworkSource = frameworkExplanation.find(s => s.used);
+                if (frameworkSource && !frameworkSource.explicit) {
+                    warnings.push(`App '${appName}' framework '${appConfig.framework}' was detected from ${frameworkSource.detectedFrom || 'dependencies'}. ` +
+                        `Add explicit 'framework: ${appConfig.framework}' for clarity.`);
+                }
+            }
+        }
+        return warnings;
+    }
+    /**
+     * Get a nested value from an object using dot notation
+     */
+    getNestedValue(obj, path) {
+        if (!obj || typeof obj !== 'object')
+            return undefined;
+        const parts = path.split('.');
+        let current = obj;
+        for (const part of parts) {
+            if (current && typeof current === 'object' && part in current) {
+                current = current[part];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return current;
+    }
+    /**
+     * Get value from a profile (handles profile-specific field names)
+     */
+    getProfileValue(profile, path) {
+        // Map common paths to profile fields
+        const mappings = {
+            'size': 'size',
+            'apps': 'apps',
+            'connect_to': 'connect_to',
+            'database.mode': 'database',
+            'branch': 'branch',
+        };
+        const field = mappings[path];
+        if (field) {
+            if (path === 'database.mode' && profile.database) {
+                return profile.database.mode;
+            }
+            return profile[field];
+        }
+        return undefined;
+    }
+    /**
+     * Get detected value from detected.yaml
+     */
+    getDetectedValue(path) {
+        if (!this.detectedConfig)
+            return undefined;
+        // Map config paths to detected config structure
+        const match = path.match(/^apps\.(\w+)\.(\w+)$/);
+        if (match) {
+            const [, appName, field] = match;
+            const detectedApp = this.detectedConfig.apps?.[appName];
+            if (detectedApp) {
+                const value = detectedApp[field];
+                const sourceField = `${field}_source`;
+                const source = detectedApp[sourceField];
+                if (value !== undefined) {
+                    return { value, source: source || 'detected.yaml' };
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get inferred value (from current config that wasn't explicitly set)
+     */
+    getInferredValue(path) {
+        const config = this.loadResult.config;
+        if (!config)
+            return undefined;
+        // Check if we have a detected config with inference info
+        if (this.detectedConfig) {
+            return this.getDetectedValue(path);
+        }
+        // For apps, we may have implicit inference based on scanning
+        const match = path.match(/^apps\.(\w+)\.(\w+)$/);
+        if (match) {
+            const [, appName, field] = match;
+            const appConfig = config.apps?.[appName];
+            if (!appConfig)
+                return undefined;
+            // These fields are commonly inferred
+            if (field === 'type' && appConfig.type) {
+                // Type was likely inferred from dependencies or naming
+                return {
+                    value: appConfig.type,
+                    source: this.inferTypeSource(appName, appConfig),
+                };
+            }
+            if (field === 'port' && appConfig.port) {
+                return {
+                    value: appConfig.port,
+                    source: 'package.json scripts (regex extraction)',
+                };
+            }
+            if (field === 'framework' && appConfig.framework) {
+                return {
+                    value: appConfig.framework,
+                    source: 'package.json dependencies',
+                };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Infer where type detection came from
+     */
+    inferTypeSource(appName, app) {
+        // Check common patterns
+        if (appName.includes('web') || appName.includes('frontend') || appName.includes('ui')) {
+            return `naming convention ('${appName}' contains frontend keyword)`;
+        }
+        if (appName.includes('api') || appName.includes('backend') || appName.includes('server')) {
+            return `naming convention ('${appName}' contains backend keyword)`;
+        }
+        if (appName.includes('worker') || appName.includes('queue')) {
+            return `naming convention ('${appName}' contains worker keyword)`;
+        }
+        // Default
+        return 'dependency analysis (react/express/@nestjs/etc.)';
+    }
+    /**
+     * Check if a field supports $detect markers
+     */
+    isDetectable(path) {
+        return DETECTABLE_FIELDS.some(pattern => {
+            const regex = new RegExp('^' + pattern.replace(/\*/g, '[^.]+') + '$');
+            return regex.test(path);
+        });
+    }
+    /**
+     * Get the final resolved value for a path
+     */
+    getFinalValue(path, profileName) {
+        const sources = this.explain(path, profileName);
+        const usedSource = sources.find(s => s.used);
+        return usedSource?.value;
+    }
+    /**
+     * Check if a value was explicitly set (not inferred/detected)
+     */
+    isExplicit(path, profileName) {
+        const sources = this.explain(path, profileName);
+        const usedSource = sources.find(s => s.used);
+        return usedSource?.explicit ?? false;
+    }
+}
+exports.ConfigExplainer = ConfigExplainer;

package/dist/detected-config.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Detected Configuration Schema
+ *
+ * This file defines the structure of .genbox/detected.yaml
+ * which is generated by 'genbox scan' and consumed by 'genbox resolve'
+ *
+ * The detected config stores auto-detected values along with
+ * metadata about how they were detected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmptyDetectedConfig = createEmptyDetectedConfig;
+exports.applyDetectedValues = applyDetectedValues;
+exports.findDetectMarkers = findDetectMarkers;
+exports.hasUnresolvedMarkers = hasUnresolvedMarkers;
+/**
+ * Create an empty detected config template
+ */
+function createEmptyDetectedConfig() {
+    return {
+        _meta: {
+            generated_at: new Date().toISOString(),
+            genbox_version: '0.0.0',
+            scanned_root: process.cwd(),
+        },
+        structure: {
+            type: 'single-app',
+            confidence: 'low',
+            indicators: [],
+        },
+        runtimes: [],
+        apps: {},
+    };
+}
+/**
+ * Merge detected values into a config, respecting $detect markers
+ */
+function applyDetectedValues(config, detected) {
+    const applied = [];
+    function walk(obj, path = '') {
+        for (const [key, value] of Object.entries(obj)) {
+            const currentPath = path ? `${path}.${key}` : key;
+            if (value === '$detect') {
+                // Replace with detected value
+                const detectedValue = getDetectedValue(detected, currentPath);
+                if (detectedValue !== undefined) {
+                    obj[key] = detectedValue;
+                    applied.push(currentPath);
+                }
+            }
+            else if (value && typeof value === 'object' && !Array.isArray(value)) {
+                walk(value, currentPath);
+            }
+        }
+    }
+    const configCopy = JSON.parse(JSON.stringify(config));
+    walk(configCopy);
+    return { config: configCopy, applied };
+}
+/**
+ * Get a detected value by config path
+ */
+function getDetectedValue(detected, path) {
+    // Handle apps.{name}.{field} pattern
+    const appMatch = path.match(/^apps\.([^.]+)\.(.+)$/);
+    if (appMatch) {
+        const [, appName, fieldPath] = appMatch;
+        const app = detected.apps[appName];
+        if (!app)
+            return undefined;
+        // Handle nested paths like commands.dev
+        const fields = fieldPath.split('.');
+        let value = app;
+        for (const field of fields) {
+            if (value && typeof value === 'object' && field in value) {
+                value = value[field];
+            }
+            else {
+                return undefined;
+            }
+        }
+        return value;
+    }
+    // Handle project.structure
+    if (path === 'project.structure') {
+        return detected.structure.type;
+    }
+    // Handle infrastructure.{name}.{field} pattern
+    const infraMatch = path.match(/^infrastructure\.([^.]+)\.(.+)$/);
+    if (infraMatch && detected.infrastructure) {
+        const [, infraName, field] = infraMatch;
+        const infra = detected.infrastructure.find(i => i.name === infraName);
+        if (infra) {
+            return infra[field];
+        }
+    }
+    // Handle git fields
+    if (path.startsWith('git.') && detected.git) {
+        const field = path.replace('git.', '');
+        return detected.git[field];
+    }
+    // Handle runtime fields
+    const runtimeMatch = path.match(/^runtimes\[(\d+)\]\.(.+)$/);
+    if (runtimeMatch && detected.runtimes) {
+        const [, index, field] = runtimeMatch;
+        const runtime = detected.runtimes[parseInt(index, 10)];
+        if (runtime) {
+            return runtime[field];
+        }
+    }
+    return undefined;
+}
+/**
+ * Get a list of all $detect markers in a config
+ */
+function findDetectMarkers(config) {
+    const markers = [];
+    function walk(obj, path = '') {
+        if (obj === '$detect') {
+            markers.push(path);
+            return;
+        }
+        if (obj && typeof obj === 'object') {
+            if (Array.isArray(obj)) {
+                obj.forEach((item, index) => {
+                    walk(item, `${path}[${index}]`);
+                });
+            }
+            else {
+                for (const [key, value] of Object.entries(obj)) {
+                    const newPath = path ? `${path}.${key}` : key;
+                    walk(value, newPath);
+                }
+            }
+        }
+    }
+    walk(config);
+    return markers;
+}
+/**
+ * Check if a config has any unresolved $detect markers
+ */
+function hasUnresolvedMarkers(config) {
+    return findDetectMarkers(config).length > 0;
+}

package/dist/index.js

@@ -24,6 +24,11 @@ const restore_db_1 = require("./commands/restore-db");
 const help_1 = require("./commands/help");
 const profiles_1 = require("./commands/profiles");
 const db_sync_1 = require("./commands/db-sync");
+const config_1 = require("./commands/config");
+const scan_1 = require("./commands/scan");
+const resolve_1 = require("./commands/resolve");
+const validate_1 = require("./commands/validate");
+const migrate_1 = require("./commands/migrate");
 program
     .addCommand(init_1.initCommand)
     .addCommand(create_1.createCommand)
@@ -39,5 +44,11 @@ program
     .addCommand(restore_db_1.restoreDbCommand)
     .addCommand(help_1.helpCommand)
     .addCommand(profiles_1.profilesCommand)
-    .addCommand(db_sync_1.dbSyncCommand);
+    .addCommand(db_sync_1.dbSyncCommand)
+    .addCommand(config_1.configCommand)
+    .addCommand(scan_1.scanCommand)
+    .addCommand(resolve_1.resolveCommand)
+    .addCommand(validate_1.validateCommand)
+    .addCommand(migrate_1.migrateCommand)
+    .addCommand(migrate_1.deprecationsCommand);
 program.parse(process.argv);