feat-forge 1.0.1

package/dist/foundation/types/Services.js

@@ -0,0 +1,156 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Type } from 'class-transformer';
+import { IsArray, IsDate, IsEnum, IsNotEmpty, IsNumber, IsOptional, IsString, Max, Min, ValidateNested } from 'class-validator';
+/**
+ * Service definition from .forge/services.json (without port)
+ */
+export class ServiceDefinition {
+    name;
+    type = 'http'; // Phase 1: HTTP only, but extensible
+    path; // HTTP only, e.g., "/api"
+}
+__decorate([
+    IsString(),
+    __metadata("design:type", String)
+], ServiceDefinition.prototype, "name", void 0);
+__decorate([
+    IsOptional(),
+    IsEnum(['http', 'tcp', 'grpc']),
+    __metadata("design:type", String)
+], ServiceDefinition.prototype, "type", void 0);
+__decorate([
+    IsOptional(),
+    IsString(),
+    __metadata("design:type", String)
+], ServiceDefinition.prototype, "path", void 0);
+/**
+ * Services declaration from .forge/services.json
+ */
+export class ServicesDTO {
+    services;
+}
+__decorate([
+    IsArray(),
+    ValidateNested({ each: true }),
+    Type(() => ServiceDefinition),
+    __metadata("design:type", Array)
+], ServicesDTO.prototype, "services", void 0);
+/**
+ * Services for a single repository
+ */
+export class RepositoryServices {
+    /**
+     * Repository name
+     */
+    name;
+    services;
+}
+__decorate([
+    IsString(),
+    IsNotEmpty(),
+    __metadata("design:type", String)
+], RepositoryServices.prototype, "name", void 0);
+__decorate([
+    ValidateNested({ each: true }),
+    Type(() => ServiceDefinition),
+    __metadata("design:type", Array)
+], RepositoryServices.prototype, "services", void 0);
+/**
+ * Service with assigned port (in generated.services.json)
+ */
+export class ServiceDefinitionWithPort extends ServiceDefinition {
+    port;
+}
+__decorate([
+    IsNumber(),
+    Min(1024),
+    Max(65535),
+    __metadata("design:type", Number)
+], ServiceDefinitionWithPort.prototype, "port", void 0);
+/**
+ * All repositories' services in a branch
+ */
+export class GeneratedServicesDTO {
+    _doNotEdit;
+    generatedAt;
+    services;
+}
+__decorate([
+    IsString(),
+    __metadata("design:type", String)
+], GeneratedServicesDTO.prototype, "_doNotEdit", void 0);
+__decorate([
+    IsDate(),
+    Type(() => Date),
+    __metadata("design:type", Date)
+], GeneratedServicesDTO.prototype, "generatedAt", void 0);
+__decorate([
+    IsArray(),
+    ValidateNested({ each: true }),
+    Type(() => ServiceDefinitionWithPort),
+    __metadata("design:type", Array)
+], GeneratedServicesDTO.prototype, "services", void 0);
+/**
+ * Root port allocations file structure
+ */
+export class PortAllocatorDTO {
+    _doNotEdit;
+    allocations;
+}
+__decorate([
+    IsString(),
+    __metadata("design:type", String)
+], PortAllocatorDTO.prototype, "_doNotEdit", void 0);
+__decorate([
+    IsArray(),
+    ValidateNested({ each: true }),
+    Type(() => BranchPortAllocationDTO),
+    __metadata("design:type", Array)
+], PortAllocatorDTO.prototype, "allocations", void 0);
+export class BranchPortAllocationDTO {
+    /**
+     * Branch name
+     */
+    name;
+    /**
+     * Starting port number for this branch's allocation range
+     */
+    start;
+    /**
+     * Ending port number for this branch's allocation range
+     */
+    end;
+    /**
+     * Services with their allocated ports for this branch
+     */
+    services; // Maps service name to its allocated port
+}
+__decorate([
+    IsString(),
+    IsNotEmpty(),
+    __metadata("design:type", String)
+], BranchPortAllocationDTO.prototype, "name", void 0);
+__decorate([
+    IsNumber(),
+    Min(1024),
+    __metadata("design:type", Number)
+], BranchPortAllocationDTO.prototype, "start", void 0);
+__decorate([
+    IsNumber(),
+    Max(65535),
+    __metadata("design:type", Number)
+], BranchPortAllocationDTO.prototype, "end", void 0);
+__decorate([
+    IsArray(),
+    ValidateNested({ each: true }),
+    Type(() => ServiceDefinitionWithPort),
+    __metadata("design:type", Array)
+], BranchPortAllocationDTO.prototype, "services", void 0);

package/dist/foundation/types/ShellName.js

@@ -0,0 +1,11 @@
+/**
+ * Supported shell types for completion script generation
+ */
+export var ShellName;
+(function (ShellName) {
+    ShellName["Bash"] = "bash";
+    ShellName["Zsh"] = "zsh";
+    ShellName["Fish"] = "fish";
+    ShellName["PowerShell"] = "powershell";
+    ShellName["Pwsh"] = "pwsh";
+})(ShellName || (ShellName = {}));

package/dist/lib/agents.js

@@ -0,0 +1,47 @@
+import path from 'path';
+import { AIAgentName } from '../foundation/types/AIAgentName.js';
+import { copyFilesWithTemplateReplacement, ensureDir } from './fs.js';
+import { SOURCE_TEMPLATE_AGENT_PATH } from './templates.js';
+export async function refreshCopilotAgentContextFiles(forgeContext, branchContext) {
+    // Need to create a .github/agents folder in the featureRoot workspace
+    const githubAgentsPath = path.join(branchContext.path, '.github', 'agents');
+    await ensureDir(githubAgentsPath);
+    const copilotSrcPath = path.join(SOURCE_TEMPLATE_AGENT_PATH, AIAgentName.COPILOT);
+    await copyFilesWithTemplateReplacement(forgeContext, branchContext, branchContext.mainRepo, copilotSrcPath, githubAgentsPath, {
+        overwrite: true,
+        dryRun: false,
+    }, SOURCE_TEMPLATE_AGENT_PATH);
+    // const copilotFiles = await readdir(path.join(SOURCE_TEMPLATE_AGENT_PATH, AIAgentName.COPILOT));
+    // // For Copilot, we basically create a symlink for each .agent.md file in :
+    // // - the .features/.template/agent/Copilot/ folder (if user doesn't have custom ones in their feature branch)
+    // // - the .features/<slug>/agent/Copilot/ folder
+    // // into the .github/agents folder of the feature workspace, so that they can be picked up by Copilot
+    // const templateCopilotAgentDir = path.join(branchContext.mainRepo.getAgentTemplatePath(AIAgentName.COPILOT));
+    // const branchCopilotAgentDir = path.join(branchContext.mainRepo.getAgentPath(branchContext.branchName, AIAgentName.COPILOT));
+    // let templateAgentFiles: string[] = [];
+    // let branchAgentFiles: string[] = [];
+    // let allAgentFiles: Map<string, string> = new Map();
+    // const matchRegex = /\.agent\.md$/;
+    // if (await pathExists(templateCopilotAgentDir)) {
+    //     templateAgentFiles = await readdir(templateCopilotAgentDir);
+    //     templateAgentFiles.forEach((file) => {
+    //         if (file.match(matchRegex)) {
+    //             allAgentFiles.set(file, path.join(templateCopilotAgentDir, file));
+    //         }
+    //     });
+    // }
+    // if (await pathExists(branchCopilotAgentDir)) {
+    //     branchAgentFiles = await readdir(branchCopilotAgentDir);
+    //     branchAgentFiles.forEach((file) => {
+    //         if (file.match(matchRegex)) {
+    //             allAgentFiles.set(file, path.join(branchCopilotAgentDir, file));
+    //         }
+    //     });
+    // }
+    // for (const agentFile of allAgentFiles.keys()) {
+    //     const sourcePath = allAgentFiles.get(agentFile)!;
+    //     const targetPath = path.join(githubAgentsPath, agentFile);
+    //     await rm(targetPath, { force: true });
+    //     await symlink(sourcePath, targetPath);
+    // }
+}

package/dist/lib/bootstrap.js

@@ -0,0 +1,54 @@
+import { execa } from 'execa';
+import path from 'path';
+import { pathExists } from './fs.js';
+import { paramsToEnv } from './env.js';
+import { getScriptExtension } from './platform.js';
+/**
+ * Execute a script file if it exists.
+ * Gracefully skips execution if the script doesn't exist.
+ *
+ * @param scriptPath - Full path to the script file
+ * @param repositoryPath - Working directory for the script execution
+ * @param scriptName - Name of the script for logging (e.g., 'bootstrap')
+ * @param params - Optional parameters to pass to the script as environment variables
+ * @returns true if script was executed, false if it didn't exist
+ */
+export async function executeScript(scriptPath, repositoryPath, scriptName, params) {
+    if (!(await pathExists(scriptPath))) {
+        return false;
+    }
+    console.log(`🔄 Executing ${scriptName} script: ${scriptPath}`);
+    try {
+        const hookEnv = paramsToEnv(params);
+        await execa(scriptPath, {
+            cwd: repositoryPath,
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                ...hookEnv,
+            },
+        });
+        console.log(`✅ ${scriptName} script completed successfully`);
+        return true;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`❌ ${scriptName} script failed: ${message}`);
+        throw error;
+    }
+}
+/**
+ * Execute a bootstrap script from a repository if it exists.
+ * Automatically selects the correct script based on the operating system (.sh or .bat).
+ * Gracefully skips execution if the script doesn't exist.
+ *
+ * @param repositoryPath - Path to the repository/worktree
+ * @param repoConfigFolderPath - Relative path to the repo config folder (e.g., '.forge')
+ * @param scriptName - Name of the script without extension (e.g., 'bootstrap')
+ * @returns true if script was executed, false if it didn't exist
+ */
+export async function executeBootstrapScript(repositoryPath, repoConfigFolderPath, scriptName = 'bootstrap') {
+    const scriptExtension = getScriptExtension();
+    const scriptPath = path.join(repositoryPath, repoConfigFolderPath, `${scriptName}${scriptExtension}`);
+    return executeScript(scriptPath, repositoryPath, scriptName);
+}

package/dist/lib/branch.js

@@ -0,0 +1,4 @@
+import path from 'path';
+export function branchNameAsPath(branchName) {
+    return branchName.split('/').join(path.sep);
+}

package/dist/lib/config.js

@@ -0,0 +1,65 @@
+import { ForgeConfigError } from '../foundation/errors/index.js';
+import { ForgeConfigFile } from '../foundation/ForgeConfigFile.js';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { readFile } from 'fs/promises';
+import path from 'path';
+import { ForgeConfig } from '../foundation/ForgeConfig.js';
+import { ForgeContext } from '../foundation/ForgeContext.js';
+import { FEAT_FORGE_CONFIG_FILE, FEAT_FORGE_CONFIG_FOLDER, FEAT_FORGE_HOME_CONFIG_FILE } from './constants.js';
+import { pathExists } from './fs.js';
+import os from 'os';
+import { mergeDropUndefined } from './merger.js';
+const HOME_CONFIG_PATH = path.join(os.homedir(), FEAT_FORGE_CONFIG_FOLDER);
+export async function getHomeDirConfigFile() {
+    const configPath = path.join(HOME_CONFIG_PATH, FEAT_FORGE_HOME_CONFIG_FILE);
+    if (!(await pathExists(configPath))) {
+        return null;
+    }
+    const raw = await readFile(configPath, 'utf8');
+    return JSON.parse(raw);
+}
+/**
+ * Find the nearest .feat-forge.json by walking up from startDir.
+ */
+export async function findConfigFilePath(startDir = process.cwd()) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const configPath = path.join(current, FEAT_FORGE_CONFIG_FILE);
+        if (await pathExists(configPath)) {
+            return configPath;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new ForgeConfigError(`Missing ${FEAT_FORGE_CONFIG_FILE}. Run the CLI from a configured root folder or start with 'forge init'.`);
+        }
+        current = parent;
+    }
+}
+/**
+ * Load and validate the Forge config from the nearest root.
+ */
+export async function loadForgeConfig(startDir = process.cwd()) {
+    const configFilePath = await findConfigFilePath(startDir);
+    const configPath = path.dirname(configFilePath);
+    try {
+        const raw = await readFile(configFilePath, 'utf8');
+        const projectConfigFile = JSON.parse(raw);
+        const homeConfigFile = await getHomeDirConfigFile();
+        const forgeConfigFile = plainToInstance(ForgeConfigFile, homeConfigFile ? mergeDropUndefined(homeConfigFile, projectConfigFile) : projectConfigFile);
+        const errors = await validate(forgeConfigFile, { whitelist: true, validationError: { target: false, value: false } });
+        if (errors.length > 0) {
+            throw new ForgeConfigError(`Invalid config file at ${configFilePath}:\n${JSON.stringify(errors, null, 2)}`);
+        }
+        return { configPath, forgeConfig: new ForgeConfig(configPath, forgeConfigFile) };
+    }
+    catch (err) {
+        const forgeConfigError = new ForgeConfigError(`Failed to load Forge config: ${err.message}`);
+        forgeConfigError.stack = err.stack;
+        throw forgeConfigError;
+    }
+}
+export async function loadForgeContext(startDir = process.cwd()) {
+    const { configPath, forgeConfig } = await loadForgeConfig(startDir);
+    return new ForgeContext(configPath, forgeConfig);
+}

package/dist/lib/constants.js

@@ -0,0 +1,13 @@
+export const FEAT_FORGE_CONFIG_FILE = '.feat-forge.json';
+export const FEAT_FORGE_CONFIG_FOLDER = '.feat-forge';
+export const FEAT_FORGE_HOME_CONFIG_FILE = 'global.config.json';
+export const TEMP_FOLDER = 'tmp';
+export const TEMP_FEATURE_INIT_FOLDER = 'feature-init';
+export const TEMP_FEATURE_ARCHIVE_FOLDER = 'feature-archive';
+export const FEAT_FORGE_SERVICES_FILE = 'services.json';
+export const FEAT_FORGE_GENERATED_SERVICES_FILE = 'generated.services.json';
+export var TemporaryFolderType;
+(function (TemporaryFolderType) {
+    TemporaryFolderType["BRANCH_INIT"] = "init";
+    TemporaryFolderType["BRANCH_ARCHIVE"] = "archive";
+})(TemporaryFolderType || (TemporaryFolderType = {}));

package/dist/lib/env.js

@@ -0,0 +1,20 @@
+/**
+ * Convert hook parameters to environment variables with a FORGE_HOOK prefix
+ * @param params - Parameters object to convert
+ * @returns Object suitable for use as env in execa
+ */
+export function paramsToEnv(params) {
+    if (!params || Object.keys(params).length === 0) {
+        return {};
+    }
+    const env = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== null && value !== undefined) {
+            // Convert to FORGE_HOOK_PARAM_NAME format and stringify
+            const slugKey = key.replace(/[^a-zA-Z0-9_]/g, '_'); // Replace non-alphanumeric characters with underscores
+            const envKey = `FORGE_HOOK_${slugKey.toUpperCase()}`;
+            env[envKey] = String(value);
+        }
+    }
+    return env;
+}

package/dist/lib/fs.js

@@ -0,0 +1,156 @@
+import { access, mkdir, readdir, readFile, rename, unlink, writeFile } from 'fs/promises';
+import path from 'path';
+import { replaceTemplateMarkers, resolveAgentFileCustomTemplate } from './templates.js';
+import { validateInput } from './validator.js';
+export async function pathExists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure a directory exists (mkdir -p behavior).
+ */
+export async function ensureDir(targetPath) {
+    await mkdir(targetPath, { recursive: true });
+}
+/**
+ * Read a UTF-8 text file.
+ */
+export async function readTextFile(targetPath) {
+    return readFile(targetPath, { encoding: 'utf8' });
+}
+/**
+ * Write a UTF-8 text file, replacing any existing content.
+ */
+export async function writeTextFile(targetPath, contents, makePath = true) {
+    if (makePath) {
+        const dir = path.dirname(targetPath);
+        await ensureDir(dir);
+    }
+    await writeFile(targetPath, contents, { encoding: 'utf8' });
+}
+/**
+ * Read a json file againt a class-validator/class-transformer class, validate and return the instance.
+ * @throws if file doesn't exist, is not valid JSON, or fails validation
+ * @returns an instance of the provided class with the file data
+ */
+export async function readJSONFile(classTransformerClass, targetPath) {
+    const content = await readTextFile(targetPath);
+    const data = JSON.parse(content);
+    return validateInput(classTransformerClass, data);
+}
+/**
+ * Write a config file atomically and create a timestamped backup if the file already exists.
+ * - If `targetPath` exists and `createBackup` is true, a backup named `${target}.bak.${iso}` is created.
+ * - Writes to a temporary file in the same directory, then renames into place.
+ */
+export async function writeConfigSafely(targetPath, contents, createBackup = true) {
+    const dir = path.dirname(targetPath);
+    await ensureDir(dir);
+    const exists = await pathExists(targetPath);
+    if (exists && createBackup) {
+        const iso = new Date().toISOString().replace(/[:]/g, '-');
+        const backupPath = `${targetPath}.bak.${iso}`;
+        await rename(targetPath, backupPath);
+    }
+    // write to temp file then rename
+    const tmpName = `.tmp.${path.basename(targetPath)}.${Date.now()}`;
+    const tmpPath = path.join(dir, tmpName);
+    try {
+        await writeFile(tmpPath, contents, { encoding: 'utf8' });
+        await rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        // cleanup temp file if something went wrong
+        try {
+            if (await pathExists(tmpPath))
+                await unlink(tmpPath);
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+}
+/**
+ * Ensure a line exists in a file (typically .gitignore).
+ * Appends the line if not present, creates the file if it doesn't exist.
+ * @returns number of lines added (0 or 1)
+ * @throws if the file exists but is not writable
+ */
+export async function ensureLineInFile(filePath, line) {
+    let content = '';
+    if (await pathExists(filePath)) {
+        content = await readTextFile(filePath);
+    }
+    const lines = content.split('\n');
+    const trimmedLine = line.trim();
+    // Check if line already exists
+    if (lines.some((l) => l.trim() === trimmedLine)) {
+        return 0;
+    }
+    // Ensure file ends with newline before adding new line
+    const needsNewline = content.length > 0 && !content.endsWith('\n');
+    const newContent = needsNewline ? `${content}\n${trimmedLine}\n` : `${content}${trimmedLine}\n`;
+    await writeTextFile(filePath, newContent);
+    return 1;
+}
+export async function copyFilesRecursively(srcDir, destDir, options = {}) {
+    const { overwrite = false, dryRun = true } = options;
+    let fileChanges = [];
+    const entries = await readdir(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            await ensureDir(destPath);
+            fileChanges = [...fileChanges, ...(await copyFilesRecursively(srcPath, destPath, options))];
+        }
+        else if (entry.isFile()) {
+            const destExists = await pathExists(destPath);
+            if (!overwrite && destExists)
+                continue; // don't overwrite existing files unless overwrite flag is set
+            if (!dryRun) {
+                let content = await readFile(srcPath, 'utf8');
+                await writeTextFile(destPath, content);
+            }
+            // Record change only if writing or would write
+            fileChanges.push(destPath);
+        }
+    }
+    return fileChanges;
+}
+export async function copyFilesWithTemplateReplacement(forgeContext, branchContext, repository, srcDir, destDir, options = {}, baseSrcDir = srcDir) {
+    const { overwrite = false, dryRun = true } = options;
+    let fileChanges = [];
+    const entries = await readdir(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcEntryPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            await ensureDir(destPath);
+            fileChanges = [
+                ...fileChanges,
+                ...(await copyFilesWithTemplateReplacement(forgeContext, branchContext, repository, srcEntryPath, destPath, options, baseSrcDir)),
+            ];
+        }
+        else if (entry.isFile()) {
+            const destExists = await pathExists(destPath);
+            if (!overwrite && destExists)
+                continue; // don't overwrite existing files unless overwrite flag is set
+            if (!dryRun) {
+                let entryRelativePath = path.relative(baseSrcDir, srcEntryPath);
+                let content = await resolveAgentFileCustomTemplate(forgeContext, repository, entryRelativePath);
+                content = replaceTemplateMarkers(content, forgeContext, branchContext, repository);
+                await writeTextFile(destPath, content);
+            }
+            // Record change only if writing or would write
+            fileChanges.push(destPath);
+        }
+    }
+    return fileChanges;
+}