@fractary/faber-cli 1.3.1 → 1.3.3

package/README.md

@@ -16,7 +16,40 @@ npx @fractary/faber-cli --help
 
 ## Quick Start
 
-### Initialize a FABER project
+### 1. Install
+
+```bash
+npm install -g @fractary/faber-cli
+```
+
+Or use directly with `npx`:
+
+```bash
+npx @fractary/faber-cli --help
+```
+
+### 2. Authenticate with GitHub
+
+**Option A: Automated Setup (Recommended)**
+
+```bash
+cd your-project
+fractary-faber auth setup
+```
+
+This command will:
+1. Detect your GitHub organization and repository
+2. Show you a URL to create a GitHub App
+3. Guide you through copying the authorization code
+4. Automatically configure FABER CLI
+
+All in ~30 seconds!
+
+**Option B: Manual Setup**
+
+See [GitHub App Setup Guide](../docs/github-app-setup.md) for detailed manual instructions.
+
+### 3. Initialize a FABER project
 
 ```bash
 fractary-faber init
@@ -191,14 +224,78 @@ All commands support:
 - `--debug` - Enable debug output
 - `--help` - Show command help
 
-## Environment Variables
+## Authentication
+
+### GitHub App Authentication (Recommended)
 
-Configure providers via environment variables:
+For enhanced security, audit trails, and enterprise readiness, use GitHub App authentication instead of Personal Access Tokens.
+
+**Quick Setup (Automated):**
+
+```bash
+fractary-faber auth setup
+```
+
+This command will guide you through creating and configuring a GitHub App in ~30 seconds.
+
+**Manual Configuration (`.fractary/settings.json`):**
+```json
+{
+  "github": {
+    "organization": "your-org",
+    "project": "your-repo",
+    "app": {
+      "id": "123456",
+      "installation_id": "12345678",
+      "private_key_path": "~/.github/faber-app.pem"
+    }
+  }
+}
+```
+
+**For CI/CD (environment variable):**
+```json
+{
+  "github": {
+    "organization": "your-org",
+    "project": "your-repo",
+    "app": {
+      "id": "123456",
+      "installation_id": "12345678",
+      "private_key_env_var": "GITHUB_APP_PRIVATE_KEY"
+    }
+  }
+}
+```
+
+```bash
+export GITHUB_APP_PRIVATE_KEY=$(cat ~/.github/faber-app.pem | base64)
+```
+
+**See detailed setup guide:** [docs/github-app-setup.md](../docs/github-app-setup.md)
+
+### Personal Access Token (Legacy)
+
+Still supported for backward compatibility:
 
 ```bash
-# GitHub
 export GITHUB_TOKEN=<token>
+```
 
+Or in `.fractary/settings.json`:
+```json
+{
+  "github": {
+    "token": "ghp_xxxxxxxxxxxx",
+    "organization": "your-org",
+    "project": "your-repo"
+  }
+}
+```
+
+### Other Providers
+
+```bash
 # Jira
 export JIRA_BASE_URL=<url>
 export JIRA_USERNAME=<username>

package/dist/commands/auth/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Authentication setup command
+ */
+import { Command } from 'commander';
+/**
+ * Create the auth setup command
+ */
+export declare function createAuthSetupCommand(): Command;
+/**
+ * Create the main auth command
+ */
+export declare function createAuthCommand(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BpC;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAehD;AAwVD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAM3C"}

package/dist/commands/auth/index.js

@@ -0,0 +1,291 @@
+/**
+ * Authentication setup command
+ */
+import { Command } from 'commander';
+import * as readline from 'readline/promises';
+import chalk from 'chalk';
+import fs from 'fs/promises';
+import { generateAppManifest, getManifestCreationUrl, exchangeCodeForCredentials, validateAppCredentials, getInstallationId, savePrivateKey, formatPermissionsDisplay, } from '../../lib/github-app-setup.js';
+import { parseCodeFromUrl, validateManifestCode, detectGitHubContext, isGitRepository, } from '../../utils/github-manifest.js';
+/**
+ * Create the auth setup command
+ */
+export function createAuthSetupCommand() {
+    return new Command('setup')
+        .description('Set up GitHub App authentication for FABER CLI')
+        .option('--org <name>', 'GitHub organization name')
+        .option('--repo <name>', 'GitHub repository name')
+        .option('--config-path <path>', 'Path to config file', '.fractary/settings.json')
+        .option('--show-manifest', 'Display manifest JSON before setup')
+        .option('--no-save', 'Display credentials without saving')
+        .action(async (options) => {
+        await runSetup(options);
+    });
+}
+/**
+ * Run the setup flow
+ */
+async function runSetup(options) {
+    console.log(chalk.bold('\n🔐 GitHub App Authentication Setup\n'));
+    // Step 1: Detect or prompt for GitHub context
+    let org = options.org;
+    let repo = options.repo;
+    if (!org || !repo) {
+        if (!isGitRepository()) {
+            console.error(chalk.red('❌ Error: Not a git repository\n') +
+                'Run this command from a git repository or provide --org and --repo flags.');
+            process.exit(1);
+        }
+        const context = detectGitHubContext();
+        if (!context) {
+            console.error(chalk.red('❌ Error: Could not detect GitHub organization/repository\n') +
+                'Please provide --org and --repo flags.');
+            process.exit(1);
+        }
+        org = context.org;
+        repo = context.repo;
+    }
+    console.log('Detected GitHub context:');
+    console.log(`  Organization: ${chalk.cyan(org)}`);
+    console.log(`  Repository: ${chalk.cyan(repo)}\n`);
+    // Step 2: Check if already configured
+    const configPath = options.configPath || '.fractary/settings.json';
+    const existingConfig = await checkExistingConfig(configPath);
+    if (existingConfig) {
+        console.log(chalk.yellow('⚠️  GitHub App already configured in ' + configPath));
+        console.log('This will create a new app and replace the existing configuration.\n');
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const answer = await rl.question('Continue? (y/N): ');
+        rl.close();
+        if (answer.toLowerCase() !== 'y') {
+            console.log('Setup cancelled.');
+            return;
+        }
+        console.log();
+    }
+    // Step 3: Generate manifest
+    const manifest = generateAppManifest({ organization: org, repository: repo });
+    if (options.showManifest) {
+        console.log(chalk.bold('\n📋 App Manifest:\n'));
+        console.log(JSON.stringify(manifest, null, 2));
+        console.log();
+    }
+    // Step 4: Display creation instructions
+    console.log(chalk.bold('━'.repeat(60)));
+    console.log(chalk.bold('📋 STEP 1: Create the GitHub App'));
+    console.log(chalk.bold('━'.repeat(60)));
+    console.log();
+    const creationUrl = getManifestCreationUrl(manifest);
+    console.log('Please click this URL to create your GitHub App:\n');
+    console.log(chalk.cyan.bold(`👉 ${creationUrl}\n`));
+    console.log('The app will request these permissions:');
+    console.log(formatPermissionsDisplay(manifest));
+    console.log();
+    const rl1 = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    await rl1.question('Press Enter when you have created the app...');
+    rl1.close();
+    // Step 5: Prompt for code
+    console.log();
+    console.log(chalk.bold('━'.repeat(60)));
+    console.log(chalk.bold('📋 STEP 2: Copy the code from the redirect URL'));
+    console.log(chalk.bold('━'.repeat(60)));
+    console.log();
+    console.log('After creating the app, GitHub will redirect you to a URL like:');
+    console.log(chalk.gray('https://github.com/settings/apps/your-app?code=XXXXXXXXXXXXX'));
+    console.log();
+    console.log('Copy the entire code from the URL bar and paste it below:\n');
+    let code = null;
+    let attempts = 0;
+    const maxAttempts = 3;
+    const rl2 = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    while (!code && attempts < maxAttempts) {
+        const input = await rl2.question(chalk.bold('Code: '));
+        // Try to parse code from URL or use directly
+        code = parseCodeFromUrl(input);
+        if (!code || !validateManifestCode(code)) {
+            attempts++;
+            if (attempts < maxAttempts) {
+                console.log(chalk.red(`\n❌ Invalid code format. Please try again (${maxAttempts - attempts} attempts remaining).\n`));
+                code = null;
+            }
+        }
+    }
+    rl2.close();
+    if (!code) {
+        console.error(chalk.red('\n❌ Error: Could not validate code after multiple attempts.\n'));
+        console.log('Please run the command again and ensure you copy the complete code.');
+        process.exit(1);
+    }
+    // Step 6: Exchange code for credentials
+    console.log(chalk.gray('\nExchanging code for credentials...'));
+    let conversionResponse;
+    try {
+        conversionResponse = await exchangeCodeForCredentials(code);
+        validateAppCredentials(conversionResponse);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(chalk.red('\n❌ Error: ' + error.message + '\n'));
+        }
+        else {
+            console.error(chalk.red('\n❌ Unknown error occurred\n'));
+        }
+        process.exit(1);
+    }
+    console.log(chalk.green('✓ App created successfully!'));
+    console.log(`  App ID: ${chalk.cyan(conversionResponse.id)}`);
+    console.log(`  App Name: ${chalk.cyan(conversionResponse.name)}\n`);
+    // Step 7: Fetch installation ID
+    console.log(chalk.gray('Fetching installation ID...'));
+    let installationId;
+    try {
+        installationId = await getInstallationId(conversionResponse.id.toString(), conversionResponse.pem, org);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(chalk.red('\n❌ Error: ' + error.message + '\n'));
+        }
+        else {
+            console.error(chalk.red('\n❌ Unknown error occurred\n'));
+        }
+        console.log('The app was created but could not find the installation.');
+        console.log(`Please install the app on your organization: ${chalk.cyan(`https://github.com/apps/${conversionResponse.slug}/installations/new`)}`);
+        process.exit(1);
+    }
+    console.log(chalk.green(`✓ Installation ID: ${chalk.cyan(installationId)}\n`));
+    // Step 8: Save private key
+    if (!options.noSave) {
+        console.log(chalk.gray(`Saving private key to ~/.github/faber-${org}.pem...`));
+        let keyPath;
+        try {
+            keyPath = await savePrivateKey(conversionResponse.pem, org);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error(chalk.red('\n❌ Error saving private key: ' + error.message + '\n'));
+            }
+            else {
+                console.error(chalk.red('\n❌ Unknown error saving private key\n'));
+            }
+            console.log('You can manually save the private key to ~/.github/ directory.');
+            process.exit(1);
+        }
+        console.log(chalk.green(`✓ Private key saved (permissions: 0600)\n`));
+        // Step 9: Update configuration
+        console.log(chalk.gray('Updating configuration...'));
+        try {
+            await updateConfig(configPath, {
+                id: conversionResponse.id.toString(),
+                installation_id: installationId,
+                private_key_path: keyPath.replace(process.env.HOME || '', '~'),
+                org,
+                repo,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error(chalk.red('\n❌ Error updating config: ' + error.message + '\n'));
+            }
+            else {
+                console.error(chalk.red('\n❌ Unknown error updating config\n'));
+            }
+            console.log('You can manually update .fractary/settings.json with:');
+            console.log(JSON.stringify({
+                github: {
+                    organization: org,
+                    project: repo,
+                    app: {
+                        id: conversionResponse.id.toString(),
+                        installation_id: installationId,
+                        private_key_path: `~/.github/faber-${org}.pem`,
+                    },
+                },
+            }, null, 2));
+            process.exit(1);
+        }
+        console.log(chalk.green(`✓ Configuration saved to ${configPath}\n`));
+    }
+    else {
+        // Display credentials without saving
+        console.log(chalk.bold('\n📋 App Credentials:\n'));
+        console.log(JSON.stringify({
+            app_id: conversionResponse.id,
+            installation_id: installationId,
+            app_slug: conversionResponse.slug,
+            private_key: '[PEM key not shown]',
+        }, null, 2));
+    }
+    // Step 10: Success message
+    console.log(chalk.bold('━'.repeat(60)));
+    console.log(chalk.bold.green('✨ Setup Complete!'));
+    console.log(chalk.bold('━'.repeat(60)));
+    console.log();
+    console.log('Test your configuration:');
+    console.log(chalk.cyan('  fractary-faber work issue fetch 1'));
+    console.log();
+    console.log('View your app:');
+    console.log(chalk.cyan(`  https://github.com/organizations/${org}/settings/apps/${conversionResponse.slug}`));
+    console.log();
+}
+/**
+ * Check if configuration already exists
+ */
+async function checkExistingConfig(configPath) {
+    try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        const config = JSON.parse(content);
+        return !!(config.github?.app);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Update configuration file
+ */
+async function updateConfig(configPath, appConfig) {
+    let config = {};
+    try {
+        const content = await fs.readFile(configPath, 'utf-8');
+        config = JSON.parse(content);
+    }
+    catch {
+        // File doesn't exist, start with empty config
+    }
+    // Update GitHub config
+    config.github = config.github || {};
+    config.github.organization = appConfig.org;
+    config.github.project = appConfig.repo;
+    config.github.app = {
+        id: appConfig.id,
+        installation_id: appConfig.installation_id,
+        private_key_path: appConfig.private_key_path,
+        created_via: 'manifest-flow',
+        created_at: new Date().toISOString(),
+    };
+    // Ensure directory exists
+    const lastSlash = configPath.lastIndexOf('/');
+    if (lastSlash > 0) {
+        const dir = configPath.substring(0, lastSlash);
+        await fs.mkdir(dir, { recursive: true });
+    }
+    // Write config
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+/**
+ * Create the main auth command
+ */
+export function createAuthCommand() {
+    const command = new Command('auth').description('Authentication management');
+    command.addCommand(createAuthSetupCommand());
+    return command;
+}

package/dist/commands/init.js

@@ -80,7 +80,7 @@ logs/session-*.md
  */
 function createDefaultConfig(preset) {
     const baseConfig = {
-        version: '1.3.1',
+        version: '1.3.2',
         preset,
         // Work tracking configuration
         work: {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CA2IxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CA4IxC"}

package/dist/index.js

@@ -14,14 +14,15 @@ import { createSpecCommand } from './commands/spec/index.js';
 import { createLogsCommand } from './commands/logs/index.js';
 import { createInitCommand } from './commands/init.js';
 import { createPlanCommand } from './commands/plan/index.js';
-const version = '1.3.1';
+import { createAuthCommand } from './commands/auth/index.js';
+const version = '1.3.2';
 /**
  * Create and configure the main CLI program
  */
 export function createFaberCLI() {
     const program = new Command('fractary-faber');
     program
-        .description('FABER development toolkit (workflow, work, repo, spec, logs)')
+        .description('FABER development toolkit (workflow, work, repo, spec, logs, auth)')
         .version(version)
         .enablePositionalOptions();
     // Global options
@@ -116,6 +117,7 @@ export function createFaberCLI() {
         cleanupCmd.parse(['', '', ...Object.entries(options).flatMap(([k, v]) => typeof v === 'boolean' && v ? [`--${k}`] : typeof v === 'string' ? [`--${k}`, v] : [])], { from: 'user' });
     });
     // Subcommand trees
+    program.addCommand(createAuthCommand());
     program.addCommand(createWorkCommand());
     program.addCommand(createRepoCommand());
     program.addCommand(createSpecCommand());

package/dist/lib/anthropic-client.js

@@ -100,7 +100,7 @@ export class AnthropicClient {
             ...planJson,
             plan_id: planId,
             created_by: 'cli',
-            cli_version: '1.3.1',
+            cli_version: '1.3.2',
             created_at: new Date().toISOString(),
             issue: {
                 source: 'github',

package/dist/lib/github-app-auth.d.ts

@@ -0,0 +1,122 @@
+/**
+ * GitHub App Authentication Module
+ *
+ * Provides JWT generation, installation token exchange, and token caching
+ * for GitHub App authentication in FABER CLI.
+ */
+import type { GitHubAppConfig } from '../types/config.js';
+/**
+ * Private Key Loader
+ *
+ * Loads private keys from file path or environment variable
+ */
+export declare class PrivateKeyLoader {
+    /**
+     * Load private key from configured sources.
+     * Priority: env var > file path
+     *
+     * @param config - GitHub App configuration
+     * @returns The private key content
+     * @throws Error if private key cannot be loaded
+     */
+    static load(config: GitHubAppConfig): Promise<string>;
+    /**
+     * Validate private key format.
+     *
+     * @param key - The private key content
+     * @returns true if valid PEM format
+     */
+    static validate(key: string): boolean;
+}
+/**
+ * GitHub App Authentication
+ *
+ * Handles JWT generation, installation token exchange, and caching
+ */
+export declare class GitHubAppAuth {
+    private cache;
+    private config;
+    private refreshPromise;
+    private static readonly REFRESH_THRESHOLD_MS;
+    private static readonly JWT_EXPIRY_SECONDS;
+    private static readonly GITHUB_API_URL;
+    constructor(config: GitHubAppConfig);
+    /**
+     * Get a valid installation token.
+     * Returns cached token if still valid, otherwise generates new one.
+     *
+     * @returns Installation access token
+     */
+    getToken(): Promise<string>;
+    /**
+     * Force refresh the token.
+     *
+     * @returns New installation access token
+     */
+    refreshToken(): Promise<string>;
+    /**
+     * Check if token needs refresh (within 5 minutes of expiration).
+     *
+     * @returns true if token should be refreshed
+     */
+    isTokenExpiringSoon(): boolean;
+    /**
+     * Validate the configuration and private key.
+     *
+     * @throws Error if configuration is invalid
+     */
+    validate(): Promise<void>;
+    /**
+     * Perform the actual token refresh
+     */
+    private doRefresh;
+    /**
+     * Generate a JWT for GitHub App authentication
+     */
+    private generateJWT;
+    /**
+     * Exchange JWT for installation access token
+     */
+    private exchangeForInstallationToken;
+    /**
+     * Check if token is expired
+     */
+    private isExpired;
+    /**
+     * Check if token is expiring soon
+     */
+    private isExpiringSoon;
+    /**
+     * Trigger background token refresh (non-blocking)
+     */
+    private triggerBackgroundRefresh;
+}
+/**
+ * Token Provider Interface
+ *
+ * Abstract interface for getting tokens, supporting both PAT and GitHub App
+ */
+export interface TokenProvider {
+    getToken(): Promise<string>;
+}
+/**
+ * Static Token Provider
+ *
+ * Simple provider for static PAT tokens
+ */
+export declare class StaticTokenProvider implements TokenProvider {
+    private token;
+    constructor(token: string);
+    getToken(): Promise<string>;
+}
+/**
+ * GitHub App Token Provider
+ *
+ * Provider that uses GitHubAppAuth for dynamic token generation
+ */
+export declare class GitHubAppTokenProvider implements TokenProvider {
+    private auth;
+    constructor(auth: GitHubAppAuth);
+    getToken(): Promise<string>;
+}
+//# sourceMappingURL=github-app-auth.d.ts.map

package/dist/lib/github-app-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app-auth.d.ts","sourceRoot":"","sources":["../../src/lib/github-app-auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAqB1D;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;OAOG;WACU,IAAI,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAiD3D;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAUtC;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,cAAc,CAAgC;IAGtD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAAiB;IAE7D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAO;IAEjD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAA4B;gBAEtD,MAAM,EAAE,eAAe;IAInC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAkBjC;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAerC;;;;OAIG;IACH,mBAAmB,IAAI,OAAO;IAK9B;;;;OAIG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB/B;;OAEG;YACW,SAAS;IAcvB;;OAEG;YACW,WAAW;IAoBzB;;OAEG;YACW,4BAA4B;IAwD1C;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,cAAc;IAItB;;OAEG;IACH,OAAO,CAAC,wBAAwB;CAUjC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,aAAa;IAC3C,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,MAAM;IAE3B,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;CAGlC;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAC9C,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAEjC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;CAGlC"}