fraim 2.0.128 → 2.0.130

package/dist/src/core/fraim-config-contract.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRAIM_CONFIG_SCHEMA = void 0;
+exports.listSupportedFraimConfigPaths = listSupportedFraimConfigPaths;
+exports.isValidFraimConfigField = isValidFraimConfigField;
+exports.sanitizeFraimConfigToSchema = sanitizeFraimConfigToSchema;
+exports.validateWorkspaceFraimConfig = validateWorkspaceFraimConfig;
+exports.assertValidWorkspaceFraimConfig = assertValidWorkspaceFraimConfig;
+const fraim_config_schema_generated_1 = require("./fraim-config-schema.generated");
+exports.FRAIM_CONFIG_SCHEMA = fraim_config_schema_generated_1.FRAIM_CONFIG_SCHEMA;
+const SUPPORTED_FRAIM_CONFIG_PATHS = [...fraim_config_schema_generated_1.SUPPORTED_FRAIM_CONFIG_PATHS];
+const SUPPORTED_FRAIM_CONFIG_PATH_SET = new Set(SUPPORTED_FRAIM_CONFIG_PATHS);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function listSupportedFraimConfigPaths() {
+    return [...SUPPORTED_FRAIM_CONFIG_PATHS];
+}
+function isValidFraimConfigField(path) {
+    if (SUPPORTED_FRAIM_CONFIG_PATH_SET.has(path)) {
+        return true;
+    }
+    for (const validField of SUPPORTED_FRAIM_CONFIG_PATH_SET) {
+        if (validField.startsWith(`${path}.`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function sanitizeNode(node, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (node.kind === 'object') {
+        if (!isPlainObject(value)) {
+            return value;
+        }
+        const sanitized = {};
+        for (const [key, child] of Object.entries(node.properties)) {
+            const childValue = sanitizeNode(child, value[key]);
+            if (childValue !== undefined) {
+                sanitized[key] = childValue;
+            }
+        }
+        return sanitized;
+    }
+    if (node.kind === 'record') {
+        if (!isPlainObject(value)) {
+            return value;
+        }
+        const sanitized = {};
+        for (const [key, entryValue] of Object.entries(value)) {
+            const childValue = sanitizeNode(node.value, entryValue);
+            if (childValue !== undefined) {
+                sanitized[key] = childValue;
+            }
+        }
+        return sanitized;
+    }
+    if (node.kind === 'array' && Array.isArray(value)) {
+        return value.map((entry) => sanitizeNode(node.element, entry));
+    }
+    return value;
+}
+function validateNode(node, value, path, issues) {
+    if (value === undefined) {
+        if (node.required) {
+            issues.push({ path, message: `${path} is required.` });
+        }
+        return;
+    }
+    switch (node.kind) {
+        case 'string':
+            if (typeof value !== 'string' || value.trim().length === 0) {
+                issues.push({ path, message: `${path} must be a non-empty string.` });
+            }
+            return;
+        case 'number':
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                issues.push({ path, message: `${path} must be a finite number.` });
+            }
+            return;
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                issues.push({ path, message: `${path} must be a boolean.` });
+            }
+            return;
+        case 'enum':
+            if (typeof value !== 'string' || !node.values.includes(value)) {
+                issues.push({ path, message: `${path} must be one of: ${node.values.join(', ')}.` });
+            }
+            return;
+        case 'array':
+            if (!Array.isArray(value)) {
+                issues.push({ path, message: `${path} must be an array.` });
+                return;
+            }
+            value.forEach((entry, index) => validateNode(node.element, entry, `${path}[${index}]`, issues));
+            return;
+        case 'record':
+            if (!isPlainObject(value)) {
+                issues.push({ path, message: `${path} must be an object.` });
+                return;
+            }
+            for (const [key, entryValue] of Object.entries(value)) {
+                validateNode(node.value, entryValue, `${path}.${key}`, issues);
+            }
+            return;
+        case 'object':
+            if (!isPlainObject(value)) {
+                issues.push({ path, message: `${path} must be an object.` });
+                return;
+            }
+            for (const key of Object.keys(value)) {
+                if (!(key in node.properties)) {
+                    issues.push({
+                        path: path ? `${path}.${key}` : key,
+                        message: `${path ? `${path}.${key}` : key} is not part of the supported FRAIM config schema.`
+                    });
+                }
+            }
+            for (const [key, child] of Object.entries(node.properties)) {
+                validateNode(child, value[key], path ? `${path}.${key}` : key, issues);
+            }
+            return;
+    }
+}
+function sanitizeFraimConfigToSchema(rawConfig) {
+    return sanitizeNode(exports.FRAIM_CONFIG_SCHEMA, rawConfig);
+}
+function validateWorkspaceFraimConfig(rawConfig) {
+    const issues = [];
+    validateNode(exports.FRAIM_CONFIG_SCHEMA, rawConfig, '', issues);
+    return issues.map((issue) => ({
+        path: issue.path || '$',
+        message: issue.message
+    }));
+}
+function assertValidWorkspaceFraimConfig(rawConfig) {
+    const issues = validateWorkspaceFraimConfig(rawConfig);
+    if (issues.length === 0) {
+        return;
+    }
+    throw new Error(`Workspace FRAIM config validation failed:\n${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join('\n')}`);
+}

package/dist/src/core/fraim-config-schema.generated.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * Generated from src/core/types.ts.
+ * This file exists so runtime validation and config token checks read the same persisted config shape the agent sees.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_FRAIM_CONFIG_PATHS = exports.FRAIM_CONFIG_SCHEMA = void 0;
+exports.FRAIM_CONFIG_SCHEMA = {
+    "kind": "object",
+    "properties": {
+        "version": {
+            "kind": "string",
+            "required": true
+        },
+        "project": {
+            "kind": "object",
+            "properties": {
+                "name": {
+                    "kind": "string",
+                    "required": true
+                },
+                "industry": {
+                    "kind": "string"
+                }
+            },
+            "required": true
+        },
+        "repository": {
+            "kind": "object",
+            "properties": {
+                "provider": {
+                    "kind": "enum",
+                    "values": [
+                        "github",
+                        "ado",
+                        "gitlab"
+                    ]
+                },
+                "owner": {
+                    "kind": "string"
+                },
+                "name": {
+                    "kind": "string"
+                },
+                "organization": {
+                    "kind": "string"
+                },
+                "project": {
+                    "kind": "string"
+                },
+                "namespace": {
+                    "kind": "string"
+                },
+                "projectPath": {
+                    "kind": "string"
+                },
+                "url": {
+                    "kind": "string"
+                },
+                "defaultBranch": {
+                    "kind": "string"
+                }
+            }
+        },
+        "issueTracking": {
+            "kind": "object",
+            "properties": {
+                "provider": {
+                    "kind": "enum",
+                    "values": [
+                        "jira",
+                        "github",
+                        "ado",
+                        "linear",
+                        "gitlab"
+                    ],
+                    "required": true
+                },
+                "owner": {
+                    "kind": "string"
+                },
+                "name": {
+                    "kind": "string"
+                },
+                "organization": {
+                    "kind": "string"
+                },
+                "project": {
+                    "kind": "string"
+                },
+                "namespace": {
+                    "kind": "string"
+                },
+                "projectPath": {
+                    "kind": "string"
+                },
+                "baseUrl": {
+                    "kind": "string"
+                },
+                "projectKey": {
+                    "kind": "string"
+                },
+                "branchPattern": {
+                    "kind": "string"
+                },
+                "apiToken": {
+                    "kind": "string"
+                },
+                "email": {
+                    "kind": "string"
+                },
+                "apiKey": {
+                    "kind": "string"
+                },
+                "teamId": {
+                    "kind": "string"
+                }
+            }
+        },
+        "mode": {
+            "kind": "enum",
+            "values": [
+                "conversational",
+                "integrated",
+                "split"
+            ]
+        },
+        "customizations": {
+            "kind": "object",
+            "properties": {
+                "architectureDoc": {
+                    "kind": "string"
+                },
+                "designSystem": {
+                    "kind": "object",
+                    "properties": {
+                        "path": {
+                            "kind": "string"
+                        },
+                        "brand": {
+                            "kind": "string"
+                        }
+                    }
+                },
+                "validation": {
+                    "kind": "object",
+                    "properties": {
+                        "buildCommand": {
+                            "kind": "string"
+                        },
+                        "testSuiteCommand": {
+                            "kind": "string"
+                        },
+                        "smokeTestCommand": {
+                            "kind": "string"
+                        }
+                    }
+                },
+                "postCleanupHook": {
+                    "kind": "string"
+                }
+            }
+        },
+        "remoteUrl": {
+            "kind": "string"
+        },
+        "apiKey": {
+            "kind": "string"
+        },
+        "competitors": {
+            "kind": "record",
+            "value": {
+                "kind": "string"
+            }
+        },
+        "compliance": {
+            "kind": "object",
+            "properties": {
+                "regulations": {
+                    "kind": "array",
+                    "element": {
+                        "kind": "string"
+                    }
+                },
+                "compliance_specifications": {
+                    "kind": "record",
+                    "value": {
+                        "kind": "string"
+                    }
+                }
+            }
+        },
+        "learning": {
+            "kind": "object",
+            "properties": {
+                "lastSynthesisDate": {
+                    "kind": "string"
+                },
+                "scoreThreshold": {
+                    "kind": "number"
+                }
+            }
+        },
+        "customer-communication": {
+            "kind": "object",
+            "properties": {
+                "productName": {
+                    "kind": "string",
+                    "required": true
+                },
+                "productUrl": {
+                    "kind": "string",
+                    "required": true
+                },
+                "senderDisplayName": {
+                    "kind": "string",
+                    "required": true
+                },
+                "senderEmail": {
+                    "kind": "string",
+                    "required": true
+                },
+                "senderReplyTo": {
+                    "kind": "string"
+                },
+                "newsletterAudienceProvider": {
+                    "kind": "string"
+                },
+                "deliveryProvider": {
+                    "kind": "string",
+                    "required": true
+                }
+            }
+        }
+    },
+    "required": true
+};
+exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
+    "version",
+    "project",
+    "project.name",
+    "project.industry",
+    "repository",
+    "repository.provider",
+    "repository.owner",
+    "repository.name",
+    "repository.organization",
+    "repository.project",
+    "repository.namespace",
+    "repository.projectPath",
+    "repository.url",
+    "repository.defaultBranch",
+    "issueTracking",
+    "issueTracking.provider",
+    "issueTracking.owner",
+    "issueTracking.name",
+    "issueTracking.organization",
+    "issueTracking.project",
+    "issueTracking.namespace",
+    "issueTracking.projectPath",
+    "issueTracking.baseUrl",
+    "issueTracking.projectKey",
+    "issueTracking.branchPattern",
+    "issueTracking.apiToken",
+    "issueTracking.email",
+    "issueTracking.apiKey",
+    "issueTracking.teamId",
+    "mode",
+    "customizations",
+    "customizations.architectureDoc",
+    "customizations.designSystem",
+    "customizations.designSystem.path",
+    "customizations.designSystem.brand",
+    "customizations.validation",
+    "customizations.validation.buildCommand",
+    "customizations.validation.testSuiteCommand",
+    "customizations.validation.smokeTestCommand",
+    "customizations.postCleanupHook",
+    "remoteUrl",
+    "apiKey",
+    "competitors",
+    "compliance",
+    "compliance.regulations",
+    "compliance.compliance_specifications",
+    "learning",
+    "learning.lastSynthesisDate",
+    "learning.scoreThreshold",
+    "customer-communication",
+    "customer-communication.productName",
+    "customer-communication.productUrl",
+    "customer-communication.senderDisplayName",
+    "customer-communication.senderEmail",
+    "customer-communication.senderReplyTo",
+    "customer-communication.newsletterAudienceProvider",
+    "customer-communication.deliveryProvider"
+];

package/dist/src/core/utils/setup-preferences.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSetupHandoffChoice = writeSetupHandoffChoice;
+exports.readSetupHandoffChoice = readSetupHandoffChoice;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_fraim_paths_1 = require("./project-fraim-paths");
+const PREFS_FILE = 'preferences.json';
+function getPrefsPath() {
+    return path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), PREFS_FILE);
+}
+function writeSetupHandoffChoice(choice) {
+    const dir = (0, project_fraim_paths_1.getUserFraimDirPath)();
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const filePath = getPrefsPath();
+    let existing = {};
+    try {
+        existing = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        // file doesn't exist or is invalid JSON — start fresh
+    }
+    existing.setupHandoffChoice = choice;
+    fs_1.default.writeFileSync(filePath, JSON.stringify(existing, null, 2));
+}
+function readSetupHandoffChoice() {
+    try {
+        const raw = fs_1.default.readFileSync(getPrefsPath(), 'utf8');
+        const data = JSON.parse(raw);
+        if (data.setupHandoffChoice === 'ide' || data.setupHandoffChoice === 'hub') {
+            return data.setupHandoffChoice;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/first-run/server.js

@@ -1,4 +1,37 @@
 "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;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9,6 +42,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const session_service_1 = require("./session-service");
+const setup_preferences_1 = require("../core/utils/setup-preferences");
 function resolveFirstRunPublicDir() {
     const candidates = [
         path_1.default.resolve(process.cwd(), 'public/first-run'),
@@ -22,31 +56,63 @@ function resolveFirstRunPublicDir() {
     }
     throw new Error('Could not locate public/first-run assets.');
 }
+/**
+ * Open the platform's native folder picker and return the chosen path
+ * (or `null` if the user cancelled).
+ *
+ * Implementation notes:
+ * - Async (`spawn`, not `spawnSync`). The folder dialog blocks until the
+ *   user dismisses it, which can be many seconds. With `spawnSync` the
+ *   entire Node event loop freezes during that time - every other HTTP
+ *   request to the FRE server gets `ERR_ABORTED`, and the FRE looks dead.
+ * - Windows: PowerShell needs `-STA` (Single-Threaded Apartment) for
+ *   `System.Windows.Forms.FolderBrowserDialog` to work. We also create a
+ *   hidden `$owner` form with `TopMost = $true` and pass it as the
+ *   dialog's owner so the picker comes to the foreground instead of
+ *   appearing behind the browser (which made the Browse button look
+ *   broken).
+ */
 function pickProjectPath() {
+    // Return contract: Promise<string | null>
     if (process.platform === 'win32') {
         const script = [
             'Add-Type -AssemblyName System.Windows.Forms',
             '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+            '$dialog.Description = "Select a FRAIM project folder"',
             '$dialog.ShowNewFolderButton = $true',
-            'if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) {',
+            // Hidden owner form forces the dialog above the user's browser. Without
+            // this the dialog often appears behind the browser tab and the user
+            // sees nothing happen when they click Browse.
+            '$owner = New-Object System.Windows.Forms.Form',
+            '$owner.TopMost = $true',
+            '$owner.ShowInTaskbar = $false',
+            'if ($dialog.ShowDialog($owner) -eq [System.Windows.Forms.DialogResult]::OK) {',
             '  Write-Output $dialog.SelectedPath',
             '}',
+            '$owner.Dispose()',
         ].join('; ');
-        const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-Command', script], {
-            encoding: 'utf8',
-        });
-        return result.status === 0 ? result.stdout.trim() || null : null;
+        return runPickerProcess('powershell', ['-NoProfile', '-STA', '-Command', script]);
     }
     if (process.platform === 'darwin') {
-        const result = (0, child_process_1.spawnSync)('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")'], {
-            encoding: 'utf8',
-        });
-        return result.status === 0 ? result.stdout.trim() || null : null;
+        return runPickerProcess('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")']);
     }
-    const result = (0, child_process_1.spawnSync)('bash', ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null'], {
-        encoding: 'utf8',
+    return runPickerProcess('bash', ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null']);
+}
+function runPickerProcess(command, args) {
+    return new Promise((resolve) => {
+        const proc = (0, child_process_1.spawn)(command, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        proc.stdout?.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+        proc.stderr?.on('data', () => { });
+        proc.on('close', () => {
+            const trimmed = stdout.trim();
+            resolve(trimmed || null);
+        });
+        proc.on('error', () => resolve(null));
     });
-    return result.status === 0 ? result.stdout.trim() || null : null;
 }
 function isCanonicalRowId(value) {
     return typeof value === 'string' && session_service_1.FIRST_RUN_ROW_IDS.includes(value);
@@ -125,9 +191,9 @@ class FirstRunServer {
                 return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not change agent.' });
             }
         });
-        this.app.post('/api/first-run/project-path/pick', (_req, res) => {
+        this.app.post('/api/first-run/project-path/pick', async (_req, res) => {
             try {
-                const selectedPath = pickProjectPath();
+                const selectedPath = await pickProjectPath();
                 if (!selectedPath) {
                     return res.status(204).end();
                 }
@@ -138,16 +204,50 @@ class FirstRunServer {
             }
         });
         this.app.post('/api/first-run/finish', (_req, res) => {
+            // Note: /finish writes the next-prompt artifact but does NOT trigger
+            // process shutdown. In v1 the Hub server is started in-process by
+            // /open-hub - if we resolved the finishPromise here, runFirstRun
+            // would call server.stop() and the parent process would exit,
+            // taking the just-started Hub down with it. The Hub handoff has
+            // to keep the parent alive. The CLI exits when the user Ctrl+Cs
+            // the terminal. v2 (#355) replaces this with a detached launcher.
             const result = this.sessionService.finish();
-            this.finishResolver?.();
             return res.json(result);
         });
-        // Hub-launch helper — starts an AiHubServer for the chosen project and
+        this.app.get('/api/first-run/ide-commands', async (_req, res) => {
+            try {
+                const { detectInstalledIDEs } = await Promise.resolve().then(() => __importStar(require('../cli/setup/ide-detector')));
+                const { describeOnboardingInvocationSurfaces } = await Promise.resolve().then(() => __importStar(require('../cli/setup/ide-global-integration')));
+                const configuredIDEs = detectInstalledIDEs();
+                const commands = describeOnboardingInvocationSurfaces(configuredIDEs);
+                return res.json({ commands });
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not load IDE commands.' });
+            }
+        });
+        this.app.post('/api/first-run/set-preference', (req, res) => {
+            const { choice } = req.body || {};
+            if (choice !== 'ide' && choice !== 'hub') {
+                return res.status(400).json({ error: 'choice must be "ide" or "hub"' });
+            }
+            (0, setup_preferences_1.writeSetupHandoffChoice)(choice);
+            return res.json({ ok: true });
+        });
+        // Hub-launch helper - starts an AiHubServer for the chosen project and
         // opens the user's browser. v2 (#355) replaces the in-process spawn with
-        // a durable launcher binary.
+        // a durable launcher binary that survives independently.
         this.app.post('/api/first-run/open-hub', async (_req, res) => {
             try {
-                return res.json(await this.sessionService.openHub());
+                const result = await this.sessionService.openHub();
+                // Write the next-prompt artifact as a side effect of opening the
+                // Hub so the client doesn't need a separate /finish call. We
+                // intentionally do NOT resolve the finishPromise - see /finish
+                // handler comment above.
+                if (result.ok) {
+                    this.sessionService.finish();
+                }
+                return res.json(result);
             }
             catch (error) {
                 return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not open Hub.' });