feat-forge 1.0.3 → 1.2.3

package/README.md

@@ -1,14 +1,20 @@
 # FeatForge
 
+[![CI](https://github.com/lixus3d/feat-forge-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/lixus3d/feat-forge-cli/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/feat-forge)](https://www.npmjs.com/package/feat-forge)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18?logo=vitest&logoColor=white)](https://vitest.dev/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/lixus3d/feat-forge-cli/pulls)
+
 **FeatForge** is a feature-first workflow and CLI (`forge`) to help you build software at scale, with (or without) AI agents.
 
 Its goal is to make the specification of features explicit and separate the thinking/specifying phase from the coding/implementation phase, across multiple agents and repositories, while keeping everything organized and traceable.
 
-With **FeatForge** you will be able to :
+With **FeatForge** you will be able to:
 
 - Parallelize work on multiple features:
     - across multiple repositories.
-    - accross multiple agents.
+    - across multiple agents.
     - while keeping track of everything.
 - Come back to any feature after days/weeks and immediately understand its initial specifications.
 - Change agent configurations and prompts on a per-feature basis.
@@ -20,7 +26,7 @@ With **FeatForge** you will be able to :
 - Not opinionated about how you specify features, how you implement them, or how you use agents. It just provides a structure (yet customizable) and a workflow to keep everything organized and traceable.
 - Partially tested with : Copilot, Codex, Claude code (+Ollama, LM-Studio). But it should work with any agent that can be configured to read/write files in the `.active-spec` folders.
 
-**_This is an expirement, trying to mix between classic development and vibe-coding in large project with quality and sustainability in mind by making specification explicit and separating thinking from coding accross multiple agents and repositories._**
+**_This is an experiment, trying to mix between classic development and vibe-coding in large project with quality and sustainability in mind by making specification explicit and separating thinking from coding across multiple agents and repositories._**
 
 ## Key Concepts
 
@@ -37,7 +43,7 @@ With **FeatForge** you will be able to :
 ## Installation
 
 ```bash
-npm install -g feat-forge-cli
+npm install -g feat-forge
 forge --version
 ```
 
@@ -110,7 +116,7 @@ forge-project-root/
 ## Modes
 
 Each branch has a mode stored in `.specs/<slug>/.forge-mode`. Switching modes updates agent adapter files with the corresponding templates.
-Agent name are useful when calling subagent
+Agent names are useful when calling subagents.
 
 Built-in modes:
 
@@ -296,6 +302,23 @@ Refresh agent adapter files for the nearest branch.
 
 Scan repositories for service declarations and generate configuration with allocated ports.
 
+Service declarations are read from `.forge/services.json` in each repository. You can define an optional dedicated health endpoint per service:
+
+```json
+{
+  "services": [
+    {
+      "name": "api",
+      "type": "http",
+      "path": "/api",
+      "healthCheckPath": "/health"
+    }
+  ]
+}
+```
+
+If `healthCheckPath` is omitted, proxy health checks fallback to `path`, then `/`.
+
 ---
 
 ### `forge services list [branch]`
@@ -348,3 +371,11 @@ For all commands and options:
 ```bash
 forge --help
 ```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and contribution workflow.
+
+# License
+
+[![License: AGPL-3.0](https://img.shields.io/npm/l/feat-forge)](./LICENSE)

package/dist/cli.js

@@ -4,6 +4,7 @@ import 'reflect-metadata';
 import { Command } from 'commander';
 import { AgentCommands } from './commands/AgentCommands.js';
 import { MaintenanceCommands } from './commands/MaintenanceCommands.js';
+import { AliasCommands } from './commands/AliasCommands.js';
 import { CompletionCommands } from './commands/CompletionCommands.js';
 import { FeatureCommands } from './commands/FeatureCommands.js';
 import { InitCommands } from './commands/InitCommands.js';
@@ -91,6 +92,11 @@ function genericBranchTypeCommands(baseCommand, handlers, subType = null) {
         .argument(`[${argName}]`, argDesc)
         .description(`Open the given ${subType ? subType + ' ' : ''}branch in the configured IDE (if no ${subType ? subType + ' ' : ''}branch is given, opens the nearest ${subType ? subType + ' ' : ''}branch)`)
         .action(handlers.open.bind(handlers));
+    baseCommand
+        .command('path')
+        .argument(`[${argName}]`, argDesc)
+        .description(`Print the worktree path of a ${subType ? subType + ' ' : ''}branch (useful for shell integration: cd "$(forge path <name>)")`)
+        .action(handlers.path.bind(handlers));
     baseCommand
         .command('merge')
         .argument(`<${argName}>`, argDesc)
@@ -221,6 +227,29 @@ function registerProxyCommands(program, context) {
         await handlers.start(options);
     });
 }
+/*
+ * Register alias commands with the CLI.
+ * This command works without config.
+ */
+function registerAliasCommands(program) {
+    const handlers = new AliasCommands();
+    const validShells = [ShellName.Bash, ShellName.Zsh, ShellName.Fish, ShellName.PowerShell, ShellName.Pwsh];
+    function isValidShellName(value) {
+        return validShells.includes(value);
+    }
+    program
+        .command('alias <shell>')
+        .description(`Generate shell aliases for feat-forge (${validShells.join(', ')})`)
+        .option('--prefix <prefix>', 'Prefix for alias names', 'ff')
+        .action((shell, options) => {
+        if (!isValidShellName(shell)) {
+            console.error(`Error: Unsupported shell type "${shell}". Supported shells: ${validShells.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        handlers.generate(shell, options.prefix);
+    });
+}
 /*
  * Register completion commands with the CLI.
  * This command works both with and without config.
@@ -263,13 +292,16 @@ async function main() {
     program.name('forge').description('Feat-Forge workflow CLI').version(packageJson.version);
     // Init command doesn't need config
     registerInitCommands(program);
+    // Alias command doesn't need config
+    registerAliasCommands(program);
     // Completion command should work with or without config
     // Register it early so it's available even without .feat-forge.json
     let context;
     // Load config for other commands
     const isInitCommand = process.argv[2] === 'init';
+    const isAliasCommand = process.argv[2] === 'alias';
     const isCompletionCommand = process.argv[2] === 'completion';
-    if (!isInitCommand) {
+    if (!isInitCommand && !isAliasCommand) {
         try {
             context = await loadForgeContext();
         }

package/dist/commands/AliasCommands.js

@@ -0,0 +1,245 @@
+import { ShellName } from '../foundation/types/ShellName.js';
+/**
+ * Commands for generating shell aliases for feat-forge.
+ */
+export class AliasCommands {
+    /**
+     * Generate and print shell aliases for the specified shell.
+     */
+    generate(shell, prefix) {
+        let output;
+        switch (shell) {
+            case ShellName.Bash:
+                output = this.generateBashAliases(prefix);
+                break;
+            case ShellName.Zsh:
+                output = this.generateZshAliases(prefix);
+                break;
+            case ShellName.Fish:
+                output = this.generateFishAliases(prefix);
+                break;
+            case ShellName.PowerShell:
+            case ShellName.Pwsh:
+                output = this.generatePowerShellAliases(prefix);
+                break;
+            default:
+                throw new Error(`Unsupported shell: ${shell}`);
+        }
+        console.log(output);
+    }
+    // ============================================================================
+    // PRIVATE METHODS
+    // ============================================================================
+    generateBashAliases(p) {
+        return `# feat-forge aliases (generated by: forge alias bash --prefix ${p})
+# Add to your ~/.bashrc:  source <(forge alias bash${p !== 'ff' ? ` --prefix ${p}` : ''})
+
+# Group aliases
+alias ${p}='forge'
+alias ${p}f='forge feature'
+alias ${p}i='forge fix'
+alias ${p}r='forge release'
+
+# Command shortcuts
+alias ${p}s='forge start'
+alias ${p}x='forge stop'
+alias ${p}c='forge create'
+alias ${p}o='forge open'
+alias ${p}l='forge list'
+alias ${p}m='forge merge'
+alias ${p}a='forge archive'
+
+# Feature shortcuts
+alias ${p}fs='forge feature start'
+alias ${p}fx='forge feature stop'
+alias ${p}fc='forge feature create'
+alias ${p}fo='forge feature open'
+alias ${p}fl='forge feature list'
+alias ${p}fm='forge feature merge'
+alias ${p}fa='forge feature archive'
+
+# Fix shortcuts
+alias ${p}is='forge fix start'
+alias ${p}ix='forge fix stop'
+alias ${p}ic='forge fix create'
+alias ${p}io='forge fix open'
+alias ${p}il='forge fix list'
+alias ${p}im='forge fix merge'
+alias ${p}ia='forge fix archive'
+
+# Release shortcuts
+alias ${p}rs='forge release start'
+alias ${p}rx='forge release stop'
+alias ${p}rc='forge release create'
+alias ${p}ro='forge release open'
+alias ${p}rl='forge release list'
+alias ${p}rm='forge release merge'
+alias ${p}ra='forge release archive'
+
+# cd into branch worktree
+${p}cd()  { cd "$(forge path "$@")"; }
+${p}fcd() { cd "$(forge feature path "$@")"; }
+${p}icd() { cd "$(forge fix path "$@")"; }
+${p}rcd() { cd "$(forge release path "$@")"; }
+`;
+    }
+    generateZshAliases(p) {
+        return `# feat-forge aliases (generated by: forge alias zsh --prefix ${p})
+# Add to your ~/.zshrc:  source <(forge alias zsh${p !== 'ff' ? ` --prefix ${p}` : ''})
+
+# Group aliases
+alias ${p}='forge'
+alias ${p}f='forge feature'
+alias ${p}i='forge fix'
+alias ${p}r='forge release'
+
+# Command shortcuts
+alias ${p}s='forge start'
+alias ${p}x='forge stop'
+alias ${p}c='forge create'
+alias ${p}o='forge open'
+alias ${p}l='forge list'
+alias ${p}m='forge merge'
+alias ${p}a='forge archive'
+
+# Feature shortcuts
+alias ${p}fs='forge feature start'
+alias ${p}fx='forge feature stop'
+alias ${p}fc='forge feature create'
+alias ${p}fo='forge feature open'
+alias ${p}fl='forge feature list'
+alias ${p}fm='forge feature merge'
+alias ${p}fa='forge feature archive'
+
+# Fix shortcuts
+alias ${p}is='forge fix start'
+alias ${p}ix='forge fix stop'
+alias ${p}ic='forge fix create'
+alias ${p}io='forge fix open'
+alias ${p}il='forge fix list'
+alias ${p}im='forge fix merge'
+alias ${p}ia='forge fix archive'
+
+# Release shortcuts
+alias ${p}rs='forge release start'
+alias ${p}rx='forge release stop'
+alias ${p}rc='forge release create'
+alias ${p}ro='forge release open'
+alias ${p}rl='forge release list'
+alias ${p}rm='forge release merge'
+alias ${p}ra='forge release archive'
+
+# cd into branch worktree
+${p}cd()  { cd "$(forge path "$@")"; }
+${p}fcd() { cd "$(forge feature path "$@")"; }
+${p}icd() { cd "$(forge fix path "$@")"; }
+${p}rcd() { cd "$(forge release path "$@")"; }
+`;
+    }
+    generateFishAliases(p) {
+        return `# feat-forge aliases (generated by: forge alias fish --prefix ${p})
+# Add to your ~/.config/fish/config.fish:  forge alias fish${p !== 'ff' ? ` --prefix ${p}` : ''} | source
+
+# Group aliases
+abbr -a ${p} forge
+abbr -a ${p}f 'forge feature'
+abbr -a ${p}i 'forge fix'
+abbr -a ${p}r 'forge release'
+
+# Command shortcuts
+abbr -a ${p}s 'forge start'
+abbr -a ${p}x 'forge stop'
+abbr -a ${p}c 'forge create'
+abbr -a ${p}o 'forge open'
+abbr -a ${p}l 'forge list'
+abbr -a ${p}m 'forge merge'
+abbr -a ${p}a 'forge archive'
+
+# Feature shortcuts
+abbr -a ${p}fs 'forge feature start'
+abbr -a ${p}fx 'forge feature stop'
+abbr -a ${p}fc 'forge feature create'
+abbr -a ${p}fo 'forge feature open'
+abbr -a ${p}fl 'forge feature list'
+abbr -a ${p}fm 'forge feature merge'
+abbr -a ${p}fa 'forge feature archive'
+
+# Fix shortcuts
+abbr -a ${p}is 'forge fix start'
+abbr -a ${p}ix 'forge fix stop'
+abbr -a ${p}ic 'forge fix create'
+abbr -a ${p}io 'forge fix open'
+abbr -a ${p}il 'forge fix list'
+abbr -a ${p}im 'forge fix merge'
+abbr -a ${p}ia 'forge fix archive'
+
+# Release shortcuts
+abbr -a ${p}rs 'forge release start'
+abbr -a ${p}rx 'forge release stop'
+abbr -a ${p}rc 'forge release create'
+abbr -a ${p}ro 'forge release open'
+abbr -a ${p}rl 'forge release list'
+abbr -a ${p}rm 'forge release merge'
+abbr -a ${p}ra 'forge release archive'
+
+# cd into branch worktree
+function ${p}cd; cd (forge path $argv); end
+function ${p}fcd; cd (forge feature path $argv); end
+function ${p}icd; cd (forge fix path $argv); end
+function ${p}rcd; cd (forge release path $argv); end
+`;
+    }
+    generatePowerShellAliases(p) {
+        return `# feat-forge aliases (generated by: forge alias powershell --prefix ${p})
+# Add to your $PROFILE:  forge alias powershell${p !== 'ff' ? ` --prefix ${p}` : ''} | Out-String | Invoke-Expression
+
+# Group functions
+function ${p} { forge @args }
+function ${p}f { forge feature @args }
+function ${p}i { forge fix @args }
+function ${p}r { forge release @args }
+
+# Command shortcuts
+function ${p}s { forge start @args }
+function ${p}x { forge stop @args }
+function ${p}c { forge create @args }
+function ${p}o { forge open @args }
+function ${p}l { forge list @args }
+function ${p}m { forge merge @args }
+function ${p}a { forge archive @args }
+
+# Feature shortcuts
+function ${p}fs { forge feature start @args }
+function ${p}fx { forge feature stop @args }
+function ${p}fc { forge feature create @args }
+function ${p}fo { forge feature open @args }
+function ${p}fl { forge feature list @args }
+function ${p}fm { forge feature merge @args }
+function ${p}fa { forge feature archive @args }
+
+# Fix shortcuts
+function ${p}is { forge fix start @args }
+function ${p}ix { forge fix stop @args }
+function ${p}ic { forge fix create @args }
+function ${p}io { forge fix open @args }
+function ${p}il { forge fix list @args }
+function ${p}im { forge fix merge @args }
+function ${p}ia { forge fix archive @args }
+
+# Release shortcuts
+function ${p}rs { forge release start @args }
+function ${p}rx { forge release stop @args }
+function ${p}rc { forge release create @args }
+function ${p}ro { forge release open @args }
+function ${p}rl { forge release list @args }
+function ${p}rm { forge release merge @args }
+function ${p}ra { forge release archive @args }
+
+# cd into branch worktree
+function ${p}cd { Set-Location (forge path @args) }
+function ${p}fcd { Set-Location (forge feature path @args) }
+function ${p}icd { Set-Location (forge fix path @args) }
+function ${p}rcd { Set-Location (forge release path @args) }
+`;
+    }
+}

package/dist/commands/BranchCommands.js

@@ -192,6 +192,18 @@ export class BranchCommands extends AbstractCommands {
             process.exitCode = 1;
         });
     }
+    /**
+     * Print the path of a branch worktree directory.
+     * Outputs only the path to stdout, suitable for shell capture: cd "$(forge path <branch>)"
+     *
+     * @param rawSlug - Optional branch slug. If not provided, finds the nearest branch context.
+     */
+    async path(rawSlug) {
+        const branchContext = rawSlug
+            ? await this.context.loadBranchContext(await confirmSlugOrThrow(rawSlug))
+            : await BranchContext.findNearestBranchContext(this.context);
+        process.stdout.write(branchContext.path);
+    }
     async merge(rawSlug) {
         const branchName = await confirmSlugOrThrow(rawSlug);
         let targetRepos;