feat-forge 1.0.1

package/dist/lib/scanner.js

@@ -0,0 +1,118 @@
+import { readdir, stat, access } from 'fs/promises';
+import path from 'path';
+const DEFAULT_MAX_DEPTH = 4;
+const IGNORED_DIRS = new Set(['node_modules', 'dist', '.git']);
+async function hasSubdir(dir, sub) {
+    try {
+        const p = path.join(dir, sub);
+        await access(p);
+        const s = await stat(p);
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function readDirSafe(dir) {
+    try {
+        return await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function isIgnored(name) {
+    return IGNORED_DIRS.has(name);
+}
+export async function scanGitRepos(rootDir, maxDepth = DEFAULT_MAX_DEPTH) {
+    const results = [];
+    async function walk(dir, depth) {
+        if (depth < 0)
+            return;
+        const base = path.basename(dir);
+        if (isIgnored(base))
+            return;
+        if (await hasSubdir(dir, '.git')) {
+            results.push({ path: path.resolve(dir), name: path.basename(dir), isGit: true });
+            return;
+        }
+        const entries = await readDirSafe(dir);
+        for (const e of entries) {
+            if (!e.isDirectory())
+                continue;
+            if (isIgnored(e.name))
+                continue;
+            try {
+                await walk(path.join(dir, e.name), depth - 1);
+            }
+            catch {
+                // ignore errors per-directory
+            }
+        }
+    }
+    await walk(path.resolve(rootDir), maxDepth);
+    return results;
+}
+export async function findAncestorForgeConfig(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(current, '.feat-forge.json');
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch {
+            // not found here
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+export async function findFeatureCandidateDirs(rootDir) {
+    const results = [];
+    const maxDepth = 3;
+    async function isCandidate(dir) {
+        const name = path.basename(dir).toLowerCase();
+        if (name.includes('feature'))
+            return true;
+        if (await hasSubdir(dir, 'src'))
+            return true;
+        try {
+            await access(path.join(dir, 'package.json'));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function walk(dir, depth) {
+        if (depth < 0)
+            return;
+        const base = path.basename(dir);
+        if (isIgnored(base))
+            return;
+        const entries = await readDirSafe(dir);
+        try {
+            if (await isCandidate(dir)) {
+                results.push(path.resolve(dir));
+                return;
+            }
+        }
+        catch {
+            // ignore
+        }
+        for (const e of entries) {
+            if (!e.isDirectory())
+                continue;
+            if (isIgnored(e.name))
+                continue;
+            await walk(path.join(dir, e.name), depth - 1);
+        }
+    }
+    await walk(path.resolve(rootDir), maxDepth);
+    return results;
+}
+export default {};

package/dist/lib/services.js

@@ -0,0 +1,132 @@
+import { ForgeServicesScanError } from '../foundation/errors/index.js';
+import { GeneratedServicesDTO, ServicesDTO } from '../foundation/types/Services.js';
+import { FEAT_FORGE_GENERATED_SERVICES_FILE, FEAT_FORGE_SERVICES_FILE } from './constants.js';
+import { pathExists, readJSONFile, writeTextFile } from './fs.js';
+import { slugify } from './slug.js';
+import { ForgeError } from '../foundation/errors/ForgeError.js';
+/**
+ * Scan all repositories in a branch for .forge/services.json files
+ */
+export async function scanReposServices(branchContext) {
+    const repositories = [];
+    for (const repo of branchContext.repositories) {
+        const servicesFilePath = repo.getRepoConfigPath(FEAT_FORGE_SERVICES_FILE);
+        if (!(await pathExists(servicesFilePath))) {
+            // Repo has no services file, skip it
+            continue;
+        }
+        try {
+            const servicesFile = await readJSONFile(ServicesDTO, servicesFilePath);
+            repositories.push({ name: repo.name, services: servicesFile.services });
+        }
+        catch (error) {
+            throw ForgeServicesScanError.extend(error, `Failed to scan services from ${repo.name} at ${servicesFilePath}`);
+        }
+    }
+    return repositories;
+}
+/**
+ * Generate and write generated.services.json with port assignments
+ */
+export async function generateBranchServicesFile(branchContext, portAllocator) {
+    const branchPortAllocation = portAllocator.getAllocation(branchContext.branchName);
+    let services = [];
+    if (branchPortAllocation) {
+        services = branchPortAllocation.getServices();
+    }
+    const generatedFile = {
+        _doNotEdit: "This file is auto-generated by 'forge services scan'. Manual edits will be lost on next generation.",
+        generatedAt: new Date(),
+        services,
+    };
+    const filePath = branchContext.getInPath(FEAT_FORGE_GENERATED_SERVICES_FILE);
+    const content = JSON.stringify(generatedFile, null, 2);
+    await writeTextFile(filePath, content);
+    return { path: filePath, services };
+}
+export async function loadGeneratedServicesFile(branchContext) {
+    const filePath = branchContext.getInPath(FEAT_FORGE_GENERATED_SERVICES_FILE);
+    if (!(await pathExists(filePath))) {
+        throw new ForgeError(`❌ Generated services file not found at ${filePath}. Please run 'forge services scan' first.`);
+    }
+    try {
+        return readJSONFile(GeneratedServicesDTO, filePath);
+    }
+    catch (error) {
+        throw ForgeError.extend(error, `❌ Failed to load generated services file at ${filePath}`);
+    }
+}
+/**
+ * Generate and write .envrc with service environment variables
+ */
+export async function generateEnvrcFile(forgeContext, branchContext, services) {
+    const branchSlug = branchContext.branchNameSlug;
+    const proxyEnabled = forgeContext.options.proxy.enabled;
+    const proxyPort = forgeContext.options.proxy.port;
+    const varPrefix = forgeContext.options.proxy.environmentVariablePrefix;
+    const timestamp = new Date().toISOString();
+    const lines = [];
+    // Header
+    lines.push('# ⚠️ AUTO-GENERATED FILE - DO NOT EDIT MANUALLY');
+    lines.push(`# This file was generated by 'forge env update' at ${timestamp}`);
+    lines.push("# Any manual edits will be lost on the next 'forge env update' run");
+    lines.push('');
+    if (forgeContext.options.proxy.envrc_source_up) {
+        lines.push('# Load parent .envrc files');
+        lines.push('source_up');
+        lines.push('');
+    }
+    // Branch configuration
+    lines.push('# --------------------');
+    lines.push('# Branch configuration');
+    lines.push('# --------------------');
+    lines.push(`export ${varPrefix}BRANCH_SLUG="${branchSlug}"`);
+    lines.push(`export ${varPrefix}BRANCH_SERVICES_CONFIG="${FEAT_FORGE_GENERATED_SERVICES_FILE}"`);
+    lines.push('');
+    lines.push('# ----------------------');
+    lines.push('# Services configuration');
+    lines.push('# ----------------------');
+    for (const service of services) {
+        const { SLUG, port, url, proxyUrl, path } = getServiceOutputs(forgeContext, branchContext, service);
+        const envName = `${varPrefix}${SLUG}`;
+        lines.push(`export ${envName}_PORT=${port}`);
+        lines.push(`export ${envName}_URL=${url}`);
+        lines.push(`${proxyEnabled ? '' : '# '}export ${envName}_PROXY_URL=${proxyUrl}`);
+        if (path) {
+            lines.push(`export ${envName}_PATH="${path}"`);
+        }
+        lines.push('');
+    }
+    // Forge proxy configuration (for future use)
+    lines.push('# ------------------------------------------');
+    lines.push('# Forge proxy configuration (for future use)');
+    lines.push('# ------------------------------------------');
+    lines.push(`export ${varPrefix}PROXY_ENABLED=${proxyEnabled}`);
+    lines.push(`${proxyEnabled ? '' : '# '}export ${varPrefix}PROXY_PORT=${proxyPort}`);
+    lines.push('');
+    const content = lines.join('\n');
+    // Write to file
+    const filePath = branchContext.getInPath(forgeContext.options.proxy.envrc);
+    await writeTextFile(filePath, content);
+    return { path: filePath, env: content };
+}
+/**
+ * Get service output variable values for a service.
+ * To be used in .envrc generation or proxy configuration generation.
+ */
+export function getServiceOutputs(forgeContext, branchContext, service) {
+    const serviceSlug = slugify(service.name, false, true); // Don't allow slashes or hyphens in service slug to keep env var names clean
+    const urlSlug = slugify(service.name, false);
+    const branchSlug = branchContext.branchNameSlug;
+    const proxyPort = forgeContext.options.proxy.port;
+    return {
+        ...service,
+        branchSlug,
+        key: `${branchSlug}.${urlSlug}`,
+        slug: serviceSlug,
+        SLUG: serviceSlug.toUpperCase(),
+        urlSlug: urlSlug,
+        url: `${service.type}://localhost:${service.port}${service.path || ''}`,
+        proxyUrl: `${service.type}://${branchSlug}.${urlSlug}.localhost:${proxyPort}${service.path || ''}`,
+    };
+}

package/dist/lib/slug.js

@@ -0,0 +1,35 @@
+import { promptConfirm } from './prompt.js';
+/**
+ * Slugify a user-provided input to be filesystem and git-branch safe.
+ */
+export function slugify(input, allowSlash = false, hyphenToUnderscore = false) {
+    const trimmed = input.trim();
+    let lowered = trimmed.toLowerCase();
+    let allowedChars = allowSlash ? 'a-z0-9/_-' : 'a-z0-9_-';
+    if (hyphenToUnderscore) {
+        lowered = lowered.replace(/-/g, '_');
+    }
+    const replaceRegex = new RegExp(`[^${allowedChars}]+`, 'g');
+    const replaced = lowered.replace(replaceRegex, '-');
+    const collapsed = replaced.replace(/-+/g, '-');
+    const cleaned = collapsed.replace(/^[.-]+/, '').replace(/[-.]+$/, '');
+    return cleaned;
+}
+/**
+ * Confirm a slugified input with the user if it differs.
+ * Slash are allowed in branch names, but not in feature slugs, so we allow them optionally in the slugification step and only ask for confirmation if the slugified result differs from the input.
+ */
+export async function confirmSlugOrThrow(input, allowSlash = true) {
+    const slug = slugify(input, allowSlash);
+    if (!slug) {
+        throw new Error('Slug is empty after slugification.');
+    }
+    if (slug === input) {
+        return slug;
+    }
+    const confirmed = await promptConfirm(`Use slugified input "${slug}" instead of "${input}"?`);
+    if (!confirmed) {
+        throw new Error('Slug confirmation declined.');
+    }
+    return slug;
+}

package/dist/lib/templates.js

@@ -0,0 +1,115 @@
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'node:url';
+import os from 'os';
+import path from 'path';
+import { FEAT_FORGE_CONFIG_FOLDER } from './constants.js';
+import { pathExists, readTextFile } from './fs.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const SOURCE_TEMPLATE_PATH = path.join(__dirname, '..', 'templates');
+export const SOURCE_TEMPLATE_AGENT_PATH = path.join(SOURCE_TEMPLATE_PATH, 'agent');
+/**
+ * Return the built-in fallback template for a given spec file.
+ */
+export async function defaultFeatForgeTemplateForSpecFile(templateFileName) {
+    const templateFilePath = path.join(SOURCE_TEMPLATE_PATH, templateFileName);
+    // console.log('Looking for built-in template at', templateFilePath);
+    if (await pathExists(templateFilePath)) {
+        try {
+            return readTextFile(templateFilePath);
+        }
+        catch (error) {
+            console.error('Could not read template file, using fallback template. Error:', error);
+        }
+    }
+    // Fallback templates if built-in files are not found for some reason... (shouldn't happen in normal usage since templates are bundled, but just in case)
+    switch (templateFileName) {
+        case 'SPEC.md':
+            return `# Specifications for [Feature Title]`;
+        case 'TODO.md':
+            return '# TODO\n\n* [ ] \n';
+        default:
+            return `# ${templateFileName}`;
+    }
+}
+export async function defaultFeatForgeTemplateForAgentFile(agentFileName) {
+    const templateFilePath = path.join(SOURCE_TEMPLATE_AGENT_PATH, agentFileName);
+    // console.log('Looking for built-in template at', templateFilePath);
+    if (await pathExists(templateFilePath)) {
+        try {
+            return readTextFile(templateFilePath);
+        }
+        catch (error) {
+            console.error('Could not read agent template file, using fallback template. Error:', error);
+        }
+    }
+    return `# ${agentFileName}`;
+}
+/**
+ * Resolve a template file from repo or user overrides.
+ * Order: repo .features/.template -> ~/.feat-forge/template -> built-in.
+ */
+export async function resolveSpecFileCustomTemplate(forgeContext, repository, fileName, subdir = '') {
+    // User override in the project .feat-forge/.template/
+    const projectTemplate = path.join(forgeContext.rootDir, FEAT_FORGE_CONFIG_FOLDER, '.template', subdir, fileName);
+    if (await pathExists(projectTemplate)) {
+        return readFile(projectTemplate, 'utf8');
+    }
+    // Repo override in .specs/.template/ for all developers working on the repo (should be committed to git)
+    const repoTemplate = repository.getTemplatePath(subdir, fileName);
+    if (await pathExists(repoTemplate)) {
+        return readFile(repoTemplate, 'utf8');
+    }
+    // User override in the home directory ~/.feat-forge/.template/ (not committed, only for the current user)
+    // Basically if the user want's to override all FeatForge templates on their machine, they can put the templates in ~/.feat-forge/.template/
+    const userTemplate = path.join(os.homedir(), FEAT_FORGE_CONFIG_FOLDER, '.template', subdir, fileName);
+    if (await pathExists(userTemplate)) {
+        return readFile(userTemplate, 'utf8');
+    }
+    // Fallback to built-in templates
+    return await defaultFeatForgeTemplateForSpecFile(fileName);
+}
+export async function resolveAgentFileCustomTemplate(forgeContext, repository, agentFile, subdir = '') {
+    // User override in the project .feat-forge/.template/
+    const projectTemplate = path.join(forgeContext.rootDir, FEAT_FORGE_CONFIG_FOLDER, '.template', '.forge-agents', subdir, agentFile);
+    // console.log('Looking for agent template at', projectTemplate);
+    if (await pathExists(projectTemplate)) {
+        return readFile(projectTemplate, 'utf8');
+    }
+    // Repo override in .specs/.template/.forge-agents/ for all developers working on the repo (should be committed to git)
+    const repoTemplate = repository.getAgentTemplatePath(subdir, agentFile);
+    // console.log('Looking for agent template at', repoTemplate);
+    if (await pathExists(repoTemplate)) {
+        return readFile(repoTemplate, 'utf8');
+    }
+    // User override in the home directory ~/.feat-forge/.template/.forge-agents/
+    // Basically if the user want's to override all FeatForge templates on their machine, they can put the templates in ~/.feat-forge/.template/
+    const userTemplate = path.join(os.homedir(), FEAT_FORGE_CONFIG_FOLDER, '.template', '.forge-agents', subdir, agentFile);
+    // console.log('Looking for agent template at', userTemplate);
+    if (await pathExists(userTemplate)) {
+        return readFile(userTemplate, 'utf8');
+    }
+    // Fallback to built-in templates
+    return await defaultFeatForgeTemplateForAgentFile(agentFile);
+}
+export function replaceTemplateMarkers(templateContent, forgeContext, branchContext, repoContext) {
+    // replace %%--XXXXXXXXXXX--%% markers in the template with the corresponding content from infos
+    const regex = /%%--([A-Z_]+)--%%/g;
+    let match;
+    let result = templateContent;
+    const activeSpecFolder = forgeContext.options.folders.activeSpec;
+    while ((match = regex.exec(result)) !== null) {
+        const marker = match[1];
+        switch (marker) {
+            case 'COPILOT_SPEC_FILES':
+                // FIXME: path resolution here is hacky
+                const relativePath = repoContext ? '../..' : '.';
+                const replacement = forgeContext.config.specFiles
+                    .map((file) => `#file:${relativePath}/${activeSpecFolder}/${file}`)
+                    .join('\n');
+                result = result.replace(match[0], replacement);
+                break;
+        }
+    }
+    return result;
+}

package/dist/lib/validator.js

@@ -0,0 +1,15 @@
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+export async function validateInput(classTransformerClass, data, options) {
+    // Validate and transform using class-validator and class-transformer
+    const extractedInstance = plainToInstance(classTransformerClass, data);
+    const errors = await validate(extractedInstance, {
+        whitelist: true,
+        validationError: { target: true, value: true },
+        ...options,
+    });
+    if (errors.length > 0) {
+        throw new Error(`Invalid ${classTransformerClass.name} file :\n${JSON.stringify(errors, null, 2)}`);
+    }
+    return extractedInstance;
+}

package/dist/templates/SPEC.md

@@ -0,0 +1,21 @@
+# Goal
+
+---
+
+# Feature details
+
+-
+-
+-
+
+# Acceptance criteria
+
+-
+-
+-
+
+# Not in the perimeter
+
+-
+-
+-

package/dist/templates/TODO.md

@@ -0,0 +1,5 @@
+# TODO
+
+- [ ]
+- [ ]
+- [ ]

package/dist/templates/agent/001.general.Omnibus.agent.md

@@ -0,0 +1,4 @@
+# Agent **Omnibus**
+
+You are a generalist agent that can do a bit of everything.
+You can execute code, read and edit files, search the web, use other tools and agents, and manage your own todo list.

package/dist/templates/agent/002.discovery.Inventorius.agent.md

@@ -0,0 +1,4 @@
+# Agent **Inventorius**
+
+Help to define a functional perimeter for a feature by asking questions to the user
+and doing research online to define what are the good ideas and good practices around the subject

package/dist/templates/agent/003.design.Architecturius.agent.md

@@ -0,0 +1,8 @@
+# Agent **Architectus**
+
+Help to define a clean, maintainable code structure for the feature:
+
+- propose an architecture and module boundaries
+- suggest patterns that match the project stack
+- identify integration points and risks (DX, performance, security)
+- keep the design as simple as possible while future-proofing key decisions

package/dist/templates/agent/004.plan.Strategos.agent.md

@@ -0,0 +1,8 @@
+# Agent **Strategos**
+
+Generate a complete, actionable implementation plan:
+
+- break the feature into clear steps and milestones
+- list tasks with acceptance criteria and edge cases
+- propose an order of execution that reduces risk
+- highlight dependencies, migrations, and rollback strategies

package/dist/templates/agent/005.tdd.TestDrivenCodificius.agent.md

@@ -0,0 +1,8 @@
+# Agent **TestDrivenCodificius**
+
+Implement using a Test-Driven Development approach by orchestrating sub-agents:
+
+- write tests first (via **TestScriptor**)
+- implement the minimal code to pass tests (via **Codificius**)
+- refactor safely (via **Consolidarius**) while keeping tests green
+- rely on **TestExecutor** to run the suite frequently and confirm behavior

package/dist/templates/agent/006.code.Codificius.agent.md

@@ -0,0 +1,8 @@
+# Agent **Codificius**
+
+Implement the feature in a straightforward coding approach:
+
+- translate the plan into working code with minimal complexity
+- prefer readability and consistency with the existing codebase
+- keep changes scoped to the feature and avoid over-engineering
+- write small, reviewable commits and leave the code in a shippable state

package/dist/templates/agent/007.simplify.Consolidarius.agent.md

@@ -0,0 +1,8 @@
+# Agent **Consolidarius**
+
+Simplify and consolidate the produced code without changing behavior:
+
+- refactor duplicated code into reusable helpers/modules
+- reduce complexity and improve readability
+- introduce generic error handlers where appropriate
+- align patterns across the codebase and remove unnecessary boilerplate

package/dist/templates/agent/008.review.Auditorix.agent.md

@@ -0,0 +1,8 @@
+# Agent **Auditorix**
+
+Review the code to ensure it meets project standards:
+
+- verify style, conventions, and architecture alignment
+- detect code smells, duplicated logic, and missing edge cases
+- check security and reliability basics (inputs, errors, timeouts, logging)
+- ensure the implementation matches the plan/spec and is easy to maintain

package/dist/templates/agent/009.testwriter.TestScriptor.agent.md

@@ -0,0 +1,8 @@
+# Agent **TestScriptor**
+
+Write unit tests (and only tests) for the feature:
+
+- cover expected behavior, edge cases, and regressions
+- use the project’s testing conventions and utilities
+- keep tests readable and focused
+- avoid changing production code unless explicitly requested

package/dist/templates/agent/010.testexecutor.TestExecutor.agent.md

@@ -0,0 +1,8 @@
+# Agent **TestExecutor**
+
+Execute the test suite and validate runtime behavior:
+
+- run unit/integration tests as relevant
+- report failures with actionable diagnosis (what failed, why likely, where)
+- suggest the minimal fix and verify it by re-running tests
+- confirm the feature works end-to-end when applicable

package/dist/templates/agent/011.commit.Scribus.agent.md

@@ -0,0 +1,10 @@
+# Agent **Scribus**
+
+Propose high-quality commit messages and prepare commits for validation:
+
+- summarize changes clearly (scope + intent)
+- follow the project’s commit convention (e.g., Conventional Commits) if used
+- group commits logically (tests, refactor, feature, chore)
+- ensure the diff is clean before committing (no stray formatting/debug code)
+
+Do not commit until user validation is received.