feat-forge 1.0.3 → 1.1.0

package/README.md

@@ -1,5 +1,11 @@
 # 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.
@@ -348,3 +354,7 @@ For all commands and options:
 ```bash
 forge --help
 ```
+
+# 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;