feat-forge 1.0.1

package/dist/foundation/BranchContext.js

@@ -0,0 +1,427 @@
+import { branchNameAsPath } from '../lib/branch.js';
+import { HookEvent } from '../lib/hooks.js';
+import { replaceTemplateMarkers, resolveAgentFileCustomTemplate, resolveSpecFileCustomTemplate } from '../lib/templates.js';
+import { readdir, rm, symlink } from 'fs/promises';
+import path from 'path';
+import { refreshCopilotAgentContextFiles } from '../lib/agents.js';
+import { TemporaryFolderType } from '../lib/constants.js';
+import { ensureDir, ensureLineInFile, pathExists, readTextFile, writeTextFile } from '../lib/fs.js';
+import { getGitStatusPorcelain, runGit } from '../lib/git.js';
+import { createIDEWorkspaces } from '../lib/ide.js';
+import { promptConfirm, promptForBranch } from '../lib/prompt.js';
+import { WorktreeRepository } from './Repository.js';
+import { AIAgentName } from './types/AIAgentName.js';
+import { slugify } from '../lib/slug.js';
+import { ForgeNotInActiveBranchError } from './errors/index.js';
+export class BranchContext {
+    context;
+    branchName;
+    path;
+    repositories;
+    active;
+    constructor(context, branchName, path, repositories, active) {
+        this.context = context;
+        this.branchName = branchName;
+        this.path = path;
+        this.repositories = repositories;
+        this.active = active;
+    }
+    isRootBranch() {
+        return !this.isFeatureBranch() && !this.isFixBranch() && !this.isReleaseBranch();
+    }
+    isFeatureBranch() {
+        return this.branchName.startsWith(this.context.options.git.featureBranchPrefix);
+    }
+    isFixBranch() {
+        return this.branchName.startsWith(this.context.options.git.fixBranchPrefix);
+    }
+    isReleaseBranch() {
+        return this.branchName.startsWith(this.context.options.git.releaseBranchPrefix);
+    }
+    static async loadFromPath(context, branchName, branchRootPath) {
+        // search folder in the BranchRootPath that matches a context repository name
+        if ((await pathExists(branchRootPath)) === false) {
+            throw new Error(`Branch root path does not exist: ${branchRootPath}`);
+        }
+        const repositories = await BranchContext.loadWorktreeRepositories(context, branchRootPath);
+        return new BranchContext(context, branchName, branchRootPath, repositories, true);
+    }
+    static async loadWorktreeRepositories(context, branchRootPath) {
+        const items = await readdir(branchRootPath, { withFileTypes: true });
+        const repoDirs = items.filter((item) => item.isDirectory() && context.repositories.some((repo) => repo.name === item.name));
+        if (repoDirs.length === 0) {
+            throw new Error(`No repository folder found in Branch path: ${branchRootPath}`);
+        }
+        const repositories = repoDirs.map((dir) => {
+            const rootRepo = context.repositories.find((r) => r.name === dir.name);
+            return new WorktreeRepository(context, { name: rootRepo.name, path: path.join(branchRootPath, dir.name), main: rootRepo.main }, rootRepo);
+        });
+        return repositories;
+    }
+    static async findNearestBranchContext(context, startDir = process.cwd()) {
+        const currentDir = path.resolve(startDir);
+        const worktreesRoot = path.resolve(context.paths.worktreesRoot);
+        const matchingBranch = (await context.mainRepo.getBranches()).find((branchName) => {
+            const branchWorktreePath = context.paths.getBranchRootPath(branchName);
+            if (currentDir.startsWith(branchWorktreePath)) {
+                return true;
+            }
+            return false;
+        });
+        if (!matchingBranch) {
+            throw new ForgeNotInActiveBranchError(`No active Branch context found for current directory: ${currentDir}`);
+        }
+        // If we found a matching branch, we can directly load the Branch context from its worktree path
+        const branchRootPath = path.join(worktreesRoot, branchNameAsPath(matchingBranch));
+        return BranchContext.loadFromPath(context, matchingBranch, branchRootPath);
+    }
+    mustBeActive() {
+        if (!this.active) {
+            throw new Error('This operation requires an active Branch context.');
+        }
+    }
+    get folders() {
+        return this.context.options.folders;
+    }
+    get files() {
+        return this.context.options.files;
+    }
+    get branchNameAsPath() {
+        return branchNameAsPath(this.branchName);
+    }
+    get branchNameSlug() {
+        return slugify(this.branchName, false, false);
+    }
+    get mainRepo() {
+        return this.repositories.find((repo) => repo.main);
+    }
+    get secondaryRepos() {
+        return this.repositories.filter((repo) => !repo.main);
+    }
+    get modeFilePath() {
+        return path.join(this.path, this.context.options.files.forgeMode);
+    }
+    get activeSpecPath() {
+        return path.join(this.path, this.folders.activeSpec);
+    }
+    getInPath(...segments) {
+        return path.join(this.path, ...segments);
+    }
+    hasRepo(repoName) {
+        return this.repositories.some((repo) => repo.name === repoName);
+    }
+    getRepo(repoName) {
+        if (!this.hasRepo(repoName))
+            throw new Error(`Repository ${repoName} is not part of the Branch context`);
+        return this.repositories.find((r) => r.name === repoName);
+    }
+    async getTemporaryRepo(repoName, type) {
+        const rootRepo = this.context.getRepo(repoName);
+        const tempRepo = await rootRepo.getTemporaryWorktree(this.branchName, type);
+        this.repositories.push(tempRepo);
+        return tempRepo;
+    }
+    getTemplatePath(...segments) {
+        return this.mainRepo.getTemplatePath(...segments);
+    }
+    getAgentTemplatePath(...segments) {
+        return this.mainRepo.getAgentTemplatePath(...segments);
+    }
+    async hasModeFile() {
+        return pathExists(this.modeFilePath);
+    }
+    async getMode() {
+        const modeFile = this.modeFilePath;
+        if (!(await this.hasModeFile())) {
+            throw new Error(`Mode file not found for branch ${this.branchName}. Expected at: ${modeFile}`);
+        }
+        const raw = (await readTextFile(modeFile)).trim().toLowerCase();
+        return this.context.getMode(raw);
+    }
+    async setMode(mode) {
+        this.context.modeExistsOrThrow(mode); // will throw if mode does not exist in config
+        const modeFile = this.modeFilePath;
+        await writeTextFile(modeFile, `${mode}\n`);
+    }
+    async initMode(mode) {
+        if (!(await this.hasModeFile())) {
+            mode = mode ?? this.context.getDefaultMode().name;
+            this.context.modeExistsOrThrow(mode); // will throw if mode does not exist in config
+            await this.setMode(mode);
+        }
+    }
+    async deleteBranch() {
+        // do not allow deletion of main,master,etc branches by forge
+        if (this.context.options.git.protectedBranches.includes(this.branchName)) {
+            throw new Error(`Branch ${this.branchName} is protected and cannot be deleted.`);
+        }
+        // Must be done on all repositories, not only the one from the Branch
+        // It also makes more sense to execute this command on the "root" repositories
+        // Note: This will not work if the branch is still used by a worktree
+        await Promise.all(this.context.repositories.map((repo) => repo.deleteBranch(this.branchName)));
+    }
+    async getDirtyRepositories() {
+        this.mustBeActive();
+        const dirtyRepositories = [];
+        for (const repo of this.repositories) {
+            const status = await getGitStatusPorcelain(repo.path);
+            if (status.length > 0) {
+                dirtyRepositories.push(repo);
+            }
+        }
+        return dirtyRepositories;
+    }
+    async refreshAgentContextFiles(mode) {
+        const { agents } = this.context;
+        const modeConfig = mode ? this.context.getMode(mode) : await this.getMode();
+        // Create the root [AGENTNAME].md files in the Branch's
+        await Promise.all(agents.map(async (agent) => {
+            const targetFile = this.getInPath(agent.agentFile);
+            let content = await resolveAgentFileCustomTemplate(this.context, this.mainRepo, modeConfig.agentFile);
+            content = replaceTemplateMarkers(content, this.context, this);
+            console.log('Refreshing agent context file for agent', agent.name, 'at', targetFile);
+            return writeTextFile(targetFile, content);
+        }));
+        // Create the agent context files specific to one agent
+        await Promise.all(agents.map(async (agent) => {
+            switch (agent.name) {
+                case AIAgentName.COPILOT:
+                    // Copilot specific a .github/agents/xxxxxx.agent.md
+                    await refreshCopilotAgentContextFiles(this.context, this);
+                    break;
+            }
+        }));
+        // If agentsInEachRepo is true
+        // also create the [AGENTNAME].md files in each repository .forge-agents/ folder, so that they can be run locally to the branch
+        // Note: The idea of the .forge-agents/ folder is to not mess up with repository root [AGENTNAME].md files that might be used for other purposes
+        if (this.context.options.process.agentsInEachRepo) {
+            await Promise.all(this.repositories.map(async (repo) => {
+                return Promise.all(agents.map(async (agent) => {
+                    const targetFile = repo.getAgentPath(agent.agentFile);
+                    let content = await resolveAgentFileCustomTemplate(this.context, this.mainRepo, modeConfig.agentFile);
+                    content = replaceTemplateMarkers(content, this.context, this, repo);
+                    console.log('Refreshing agent context file for agent', agent.name, 'at', targetFile);
+                    return writeTextFile(targetFile, content);
+                }));
+            }));
+        }
+        // Execute postRefreshAgents hooks after agent context files are refreshed
+        await this.executeHook(HookEvent.POST_REFRESH_AGENTS, { branch: this.branchName });
+    }
+    /**
+     * Ensure :
+     * - .active-spec (or the cusomized name) is in .gitignore for one or more repo roots.
+     * - .forge-agents/* is in .gitignore for one or more repo roots.
+     */
+    async ensureGitIgnore(repository) {
+        let changes = 0;
+        const gitignorePath = path.join(repository.path, '.gitignore');
+        changes += await ensureLineInFile(gitignorePath, this.folders.activeSpec);
+        changes += await ensureLineInFile(gitignorePath, this.folders.repoAgents);
+        if (changes > 0) {
+            await repository.commit(`chore: add forge specific files to .gitignore`, [gitignorePath]);
+        }
+        return changes;
+    }
+    async initBranch() {
+        let hiddenChanges = 0; // Changes were made on temporary worktrees
+        for (const rootRepo of this.context.repositories) {
+            let worktreeRepo;
+            if (this.hasRepo(rootRepo.name)) {
+                // worktree already exists, we can use it to check for spec files without affecting the main branch
+                worktreeRepo = this.getRepo(rootRepo.name);
+            }
+            else {
+                worktreeRepo = await this.getTemporaryRepo(rootRepo.name, TemporaryFolderType.BRANCH_INIT);
+            }
+            // Check for spec files in the main repository
+            if (worktreeRepo.isMainRepository()) {
+                const fileChanges = await this.ensureBranchSpecFiles(worktreeRepo, this.branchName);
+                if (fileChanges.length) {
+                    await worktreeRepo.commit(`docs(${this.branchName}): init branch spec files`, fileChanges);
+                    if (worktreeRepo.temporary) {
+                        hiddenChanges += fileChanges.length;
+                    }
+                }
+            }
+            if (this.context.options.process.manageGitIgnore) {
+                const gitIgnoreChanges = await this.ensureGitIgnore(worktreeRepo);
+                if (gitIgnoreChanges > 0 && worktreeRepo.temporary) {
+                    hiddenChanges += gitIgnoreChanges;
+                }
+            }
+            if (worktreeRepo.temporary) {
+                await worktreeRepo.remove();
+            }
+        }
+        return hiddenChanges;
+    }
+    /**
+     * Ensure the spec files exist for a branch directory without overwriting existing files.
+     * Also creates the agent subdirectory (empty, ready for symlinks).
+     */
+    async ensureBranchSpecFiles(repo, branchName) {
+        repo.mustBeMainRepository();
+        let fileChanges = [];
+        const branchSpecPath = repo.getSpecPath(branchName);
+        await ensureDir(branchSpecPath);
+        // Create main spec files
+        for (const fileName of this.context.config.specFiles) {
+            const filePath = path.join(branchSpecPath, fileName);
+            if (await pathExists(filePath)) {
+                continue;
+            }
+            const content = await resolveSpecFileCustomTemplate(this.context, repo, fileName);
+            await writeTextFile(filePath, content);
+            fileChanges.push(filePath);
+        }
+        return fileChanges;
+    }
+    async start() {
+        const branchRoot = this.path;
+        await ensureDir(branchRoot);
+        this.repositories = await this.ensureWorktrees();
+        // Set active Branch pointer
+        await this.setActiveSpec();
+        // Set initial mode to spec if not defined
+        await this.initMode(); // default to spec mode on start
+        // Refresh agent context files based on mode (will create symlinks to template files or user overrides)
+        await this.refreshAgentContextFiles();
+        // Create IDE workspaces if configured
+        if (this.context.ides.length > 0) {
+            await createIDEWorkspaces(this.branchName, this.path, this.mainRepo.name, this.repositories, this.context.ides, this.context.agents);
+        }
+        // Execute bootstrap scripts in each repository
+        for (const repository of this.repositories) {
+            try {
+                // Copy configured files from root repos to worktrees
+                await repository.rootRepository.copyFilesToWorktree(repository);
+                // Execute bootstrap script if defined in the repository
+                await repository.executeBootstrapScript();
+            }
+            catch (error) {
+                // Soft error here, so that the Branch can still be started even if a bootstrap script fails, which can be useful for debugging or if the bootstrap script is not critical
+                console.error(`❌ Failed to execute bootstrap script in ${repository.name}`, error);
+            }
+        }
+        // Execute postBranchStart hooks in each repository
+        await this.executeHook(HookEvent.POST_START, { branch: this.branchName });
+        this.active = true;
+    }
+    /**
+     * Execute hooks for a specific event across all repositories in this branch.
+     * Soft errors are used so that the branch operation can continue even if a hook fails.
+     *
+     * Hook parameters are passed to scripts as environment variables with FORGE_HOOK_ prefix.
+     * Example: params { sourceBranch: 'feature/xyz' } becomes FORGE_HOOK_SOURCEBRANCH
+     *
+     * @param eventType - Type of hook event to execute
+     * @param params - Optional parameters to pass to hooks as environment variables
+     */
+    async executeHook(eventType, params) {
+        for (const repository of this.repositories) {
+            try {
+                const executedHooks = await repository.executeHook(eventType, params);
+                if (executedHooks.length > 0) {
+                    console.log(`📌 Executed ${executedHooks.length} ${eventType} hook(s) in ${repository.name}: ${executedHooks.join(', ')}`);
+                }
+            }
+            catch (error) {
+                // Soft error: allow the branch operation to continue even if a hook fails
+                console.error(`❌ Failed to execute ${eventType} hooks in ${repository.name}`, error);
+            }
+        }
+    }
+    async ensureWorktrees() {
+        return Promise.all(this.context.repositories.map((repo) => {
+            return this.ensureWorktreeForRepo(repo);
+        }));
+    }
+    async ensureWorktreeForRepo(repo) {
+        if (await repo.hasWorktree(this.branchName)) {
+            return repo.getWorktree(this.branchName);
+        }
+        else {
+            return repo.addWorktree(this.branchName);
+        }
+    }
+    async setActiveSpec() {
+        // Create .active-spec symlink in the Branch root pointing to the current spec file in the main repository worktree
+        const specRealPath = this.mainRepo.getSpecPath(this.branchName);
+        const activeSpecPath = this.activeSpecPath;
+        await rm(activeSpecPath, { force: true });
+        await symlink(path.relative(path.dirname(activeSpecPath), specRealPath), activeSpecPath);
+        // If activeSpecInEachRepo is true, also create/update .active-spec symlink in each repository worktree pointing to the same spec file in the main repository worktree
+        if (this.context.options.process.activeSpecInEachRepo) {
+            await Promise.all(this.repositories.map((repo) => repo.setActiveSpec(this)));
+        }
+    }
+    async collectRepositoriesStatus() {
+        const status = {};
+        for (const repo of this.repositories) {
+            status[repo.name] = await repo.getStatus(this.branchName);
+        }
+        return status;
+    }
+    async stop() {
+        // Execute preStop hooks before stopping the branch
+        await this.executeHook(HookEvent.PRE_STOP, { branch: this.branchName });
+        // Check for uncommitted changes in worktrees
+        const dirtyRepositories = await this.getDirtyRepositories();
+        // Handle dirty worktrees if any exist
+        if (dirtyRepositories.length > 0) {
+            for (const repo of dirtyRepositories) {
+                const repoShouldProceed = await repo.promptDirtyActions();
+                if (!repoShouldProceed) {
+                    return;
+                }
+            }
+        }
+    }
+    async delete() {
+        // Execute preDelete hooks before deleting the branch
+        await this.executeHook(HookEvent.PRE_DELETE, { branch: this.branchName });
+        // Remove worktrees for all repositories
+        await Promise.all(this.repositories.map((repo) => repo.remove()));
+        if (await pathExists(this.path)) {
+            if ((await readdir(this.path)).length !== 0) {
+                // Remove Branch path if empty
+                const confirm = await promptConfirm(`Branch path ${this.path} is not empty. Do you want to remove it?`);
+                if (!confirm) {
+                    console.log(`Please manually clean up the Branch path: ${this.path}`);
+                    return;
+                }
+            }
+            await rm(this.path, { recursive: true, force: true });
+        }
+        this.active = false;
+    }
+    async archive() {
+        await this.executeHook(HookEvent.PRE_ARCHIVE, { branch: this.branchName });
+        let worktreeRepo;
+        if (this.hasRepo(this.mainRepo.name)) {
+            // worktree already exists, we can use it to create the Branch files without affecting the main branch
+            worktreeRepo = this.getRepo(this.mainRepo.name);
+        }
+        else {
+            // create a temporary worktree to move the Branch files without affecting the main branch
+            worktreeRepo = await this.getTemporaryRepo(this.mainRepo.name, TemporaryFolderType.BRANCH_ARCHIVE);
+        }
+        const archivePath = path.join(worktreeRepo.specsArchivePath, branchNameAsPath(this.branchName));
+        const branchPath = worktreeRepo.getSpecPath(this.branchName);
+        // Create archives directory
+        await ensureDir(path.dirname(archivePath));
+        // Move Branch to archive using git mv
+        await runGit(worktreeRepo.path, ['mv', branchPath, archivePath]);
+        // Commit the archive
+        await worktreeRepo.commit(`docs(${this.branchName}): archive Branch`, [archivePath]);
+        console.log(`✓ Branch \"${this.branchName}\" archived successfully.`);
+        console.log(`  Moved: ${this.context.options.folders.specs}/${this.branchName}/ → ${this.context.options.folders.specs}/${this.context.options.folders.archive}/${this.branchName}/`);
+        // Ask for merge
+        const confirmMerge = await promptConfirm('Do you want to merge the archived branch to another branch? (recommended to keep trace in main/dev branch)');
+        if (confirmMerge) {
+            const targetBranch = await promptForBranch(this.context.mainRepo.path, 'Select target branch to merge archived branch:', this.context.options.git.featureBranchPrefix, false);
+            await worktreeRepo.rootRepository.merge(this.branchName, targetBranch);
+        }
+    }
+}

package/dist/foundation/ForgeConfig.js

@@ -0,0 +1,264 @@
+import path from 'path';
+import { FEAT_FORGE_CONFIG_FILE } from '../lib/constants.js';
+import { merge } from '../lib/merger.js';
+import { ForgeConfigError } from './errors/index.js';
+import { AIAgentName } from './types/AIAgentName.js';
+import { IDEName } from './types/IDEName.js';
+import { ForgeOptions, } from './ForgeConfigFile.js';
+export const DEFAULT_SPEC_FILES = ['SPEC.md', 'TODO.md'];
+export const DEFAULT_MODES = [
+    {
+        name: 'general',
+        agentFile: '001.general.Omnibus.agent.md',
+        description: 'Default mode with no special behavior',
+    },
+    {
+        name: 'discovery',
+        agentFile: '002.discovery.Inventorius.agent.md',
+        description: 'Help to define a functional perimeter for a feature',
+        default: true,
+    },
+    {
+        name: 'design',
+        agentFile: '003.design.Architecturius.agent.md',
+        description: 'Help to define an architecture for a feature',
+    },
+    {
+        name: 'plan',
+        agentFile: '004.plan.Strategos.agent.md',
+        description: 'Generate a plan for a feature, in SPEC.md & TODO.md by default',
+    },
+    {
+        name: 'tdd',
+        agentFile: '005.tdd.TestDrivenCodificius.agent.md',
+        description: 'Test Driven Development agent to implement the feature',
+    },
+    {
+        name: 'code',
+        agentFile: '006.code.Codificius.agent.md',
+        description: 'Code agent to implement the feature',
+    },
+    {
+        name: 'simplify',
+        agentFile: '007.simplify.Consolidarius.agent.md',
+        description: 'Simplify and consolidate the feature',
+    },
+    {
+        name: 'review',
+        agentFile: '008.review.Auditorix.agent.md',
+        description: 'Review the feature and ensure code guidelines',
+    },
+    {
+        name: 'test-writer',
+        agentFile: '009.testwriter.TestScriptor.agent.md',
+        description: 'Write unit/functional tests',
+    },
+    {
+        name: 'test-executor',
+        agentFile: '010.testexecutor.TestExecutor.agent.md',
+        description: 'Execute unit/functional tests',
+    },
+    {
+        name: 'commit',
+        agentFile: '011.commit.Scribus.agent.md',
+        description: 'Propose commit message based changes related to the feature and then commit',
+    },
+];
+export class ForgeConfig {
+    rootDir;
+    repositories;
+    agents;
+    ides;
+    options;
+    specFiles;
+    modes;
+    constructor(configPath, configFile) {
+        this.rootDir = path.resolve(configFile.rootDir ? path.resolve(configPath, configFile.rootDir) : configPath);
+        this.specFiles = configFile.specFiles || DEFAULT_SPEC_FILES;
+        // standardize config entries
+        this.modes = this.standardizeModes(configFile.modes || DEFAULT_MODES);
+        this.repositories = this.standardizeRepositories(configFile.repositories);
+        this.ides = this.standardizeIDEs(configFile.ides);
+        this.agents = this.standardizeAgents(configFile.agents);
+        this.options = this.standardizeOptions(configFile.options);
+    }
+    getPath(...segments) {
+        return path.resolve(this.rootDir, ...segments); // validate path segments
+    }
+    standardizeModes(rawModes) {
+        if (!Array.isArray(rawModes)) {
+            throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: "modes" must be an array.`);
+        }
+        if (rawModes.length === 0) {
+            throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: At least one mode must be defined in the "modes" array.`);
+        }
+        const modes = rawModes.map((entry) => {
+            const agentFile = entry.agentFile?.trim();
+            if (!agentFile) {
+                throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: Each mode entry must have a non-empty "agentFile" property.`);
+            }
+            const name = entry.name?.trim() || agentFile.replace(/\.[^/.]+$/, ''); // default name from agentFile if not provided
+            if (!name) {
+                throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: Each mode entry must have a non-empty "name" or valid "agentFile" property.`);
+            }
+            return {
+                name,
+                agentFile,
+                description: entry.description?.trim(),
+                default: !!entry.default,
+            };
+        });
+        ForgeConfig.checkDefaultMode(modes);
+        return modes;
+    }
+    standardizeRepositories(repos) {
+        const repositories = repos
+            .map((entry) => {
+            if (typeof entry === 'string') {
+                return {
+                    path: entry,
+                };
+            }
+            else
+                return entry;
+        })
+            .map((repositoryConfig) => {
+            if (typeof repositoryConfig.path !== 'string' || repositoryConfig.path.trim() === '') {
+                throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: Repository entries must have a non-empty "path".`);
+            }
+            const rootPath = repositoryConfig.path.trim();
+            return {
+                name: repositoryConfig.name ?? path.basename(rootPath),
+                path: this.getPath(rootPath),
+                main: !!(repositoryConfig.main ?? false),
+                copyFiles: repositoryConfig.copyFiles ?? [],
+            };
+        });
+        ForgeConfig.checkMainRepo(repositories);
+        return repositories;
+    }
+    standardizeIDEs(ides) {
+        if (!ides) {
+            return [];
+        }
+        if (!Array.isArray(ides)) {
+            throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: "ides" must be an array.`);
+        }
+        return ides
+            .map((entry) => {
+            if (typeof entry === 'string') {
+                return {
+                    name: entry,
+                    createWorkspace: true,
+                };
+            }
+            else
+                return entry;
+        })
+            .map((ideConfig) => {
+            // Full config object
+            const ideName = Object.values(IDEName).find((name) => name === ideConfig.name);
+            if (!ideName) {
+                throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: IDE config objects must have a valid "name" property.`);
+            }
+            return {
+                name: ideName,
+                createWorkspace: ideConfig.createWorkspace ?? true,
+                settings: ideConfig.settings ?? {},
+                openCommand: ideConfig.openCommand,
+            };
+        });
+    }
+    standardizeAgents(agents) {
+        if (!agents) {
+            return [
+                {
+                    name: null,
+                    agentFile: 'AGENTS.md',
+                    requiresIDEConfig: false,
+                },
+            ];
+        }
+        if (!Array.isArray(agents)) {
+            throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: "agents" must be an array.`);
+        }
+        return agents
+            .map((entry) => {
+            if (typeof entry === 'string') {
+                return {
+                    name: entry,
+                };
+            }
+            else
+                return entry;
+        })
+            .map((agentConfig) => {
+            const name = agentConfig.name?.trim() ?? null;
+            let agentFile = agentConfig.agentFile?.trim() ?? null;
+            if (!name && !agentFile) {
+                throw new ForgeConfigError(`Invalid ${FEAT_FORGE_CONFIG_FILE}: Agent config objects must have either a valid "name" or an "agentFile" property.`);
+            }
+            if (!agentFile) {
+                agentFile = ForgeConfig.getAgentFile(name);
+            }
+            return {
+                name,
+                agentFile,
+                requiresIDEConfig: name ? ForgeConfig.agentRequiresIDEConfig(name) : false,
+                settings: agentConfig.settings,
+            };
+        });
+    }
+    standardizeOptions(options) {
+        return merge(new ForgeOptions(), options || {});
+    }
+    static checkDefaultMode(modes) {
+        const defaultModes = modes.filter((mode) => mode.default);
+        if (defaultModes.length > 1) {
+            throw new ForgeConfigError('Multiple modes cannot be marked as default in the configuration.');
+        }
+        if (defaultModes.length === 0) {
+            modes[0].default = true; // set first mode as default if none marked
+        }
+    }
+    static checkMainRepo(repositories) {
+        if (repositories.filter((repo) => repo.main).length > 1) {
+            throw new ForgeConfigError('Multiple repositories cannot be marked as main in the configuration.');
+        }
+        let mainRepo = repositories.find((repo) => repo.main);
+        if (!mainRepo) {
+            if (repositories.length > 0) {
+                repositories[0].main = true;
+            }
+            else {
+                throw new ForgeConfigError('At least one repository must be defined in the configuration.');
+            }
+        }
+    }
+    /**
+     * Get default agent file name for known agents
+     */
+    static getAgentFile(agentName) {
+        const agentFiles = {
+            [AIAgentName.CLAUDE]: 'CLAUDE.md',
+            [AIAgentName.COPILOT]: 'AGENTS.md',
+            [AIAgentName.GEMINI]: 'GEMINI.md',
+            [AIAgentName.CODEX]: 'AGENTS.md',
+            [AIAgentName.CURSOR]: 'AGENTS.md',
+        };
+        return agentFiles[agentName] || 'AGENTS.md';
+    }
+    /**
+     * Check if agent requires IDE configuration
+     */
+    static agentRequiresIDEConfig(agentName) {
+        const agentRequiringIDEConfig = {
+            [AIAgentName.COPILOT]: true,
+            [AIAgentName.CURSOR]: true,
+            [AIAgentName.CLAUDE]: false,
+            [AIAgentName.GEMINI]: false,
+            [AIAgentName.CODEX]: false,
+        };
+        return !!agentRequiringIDEConfig[agentName];
+    }
+}