@fractary/faber-cli 1.5.12 → 1.5.13

package/README.md

@@ -1,6 +1,6 @@
 # @fractary/faber-cli
 
-Command-line interface for FABER development toolkit.
+Command-line interface for FABER development toolkit. Execute and manage FABER workflows, work items, repository operations, specifications, and logs.
 
 ## Installation
 
@@ -16,35 +16,205 @@ npx @fractary/faber-cli --help
 
 ## Quick Start
 
-### 1. Authenticate
+### 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
 ```
 
-### 2. Initialize
+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
+fractary-faber init --preset minimal
+fractary-faber init --preset enterprise
+```
+
+### Workflow Commands
+
+```bash
+# Start a FABER workflow
+fractary-faber run --work-id 123
+
+# Check workflow status
+fractary-faber status
+fractary-faber status --workflow-id <id>
+
+# Pause/resume workflows
+fractary-faber pause <workflow-id>
+fractary-faber resume <workflow-id>
+
+# Recover from checkpoint
+fractary-faber recover <workflow-id>
+
+# Clean up old workflows
+fractary-faber cleanup --max-age 30
 ```
 
-### 3. Run a Workflow
+### Work Commands
 
 ```bash
-faber plan --work-id 123
-cd ~/.claude-worktrees/{org}-{project}-123
-/fractary-faber:workflow-run 123
+# Issue operations
+fractary-faber work issue fetch 123
+fractary-faber work issue create --title "New feature"
+fractary-faber work issue update 123 --title "Updated"
+fractary-faber work issue close 123
+fractary-faber work issue search --query "bug fix"
+
+# Comment operations
+fractary-faber work comment create 123 --body "This is a comment"
+fractary-faber work comment list 123
+
+# Label operations
+fractary-faber work label add 123 --label "bug,critical"
+fractary-faber work label remove 123 --label "wontfix"
+fractary-faber work label list
+
+# Milestone operations
+fractary-faber work milestone create --title "v1.0" --due-on "2025-12-31"
+fractary-faber work milestone list
+fractary-faber work milestone set 123 --milestone "v1.0"
+```
+
+### Repository Commands
+
+```bash
+# Branch operations
+fractary-faber repo branch create "feat/new-feature"
+fractary-faber repo branch list
+fractary-faber repo branch delete feat/old-feature
+
+# Commit operations
+fractary-faber repo commit "feat: add new feature"
+
+# Pull request operations
+fractary-faber repo pr create "Add new feature" --body "Description"
+fractary-faber repo pr list
+fractary-faber repo pr merge 42
+fractary-faber repo pr review 42
+
+# Tag operations
+fractary-faber repo tag create v1.0.0
+fractary-faber repo tag push v1.0.0
+fractary-faber repo tag list
+
+# Worktree operations
+fractary-faber repo worktree create feat/new-feature
+fractary-faber repo worktree list
+fractary-faber repo worktree remove feat/new-feature
 ```
 
-## Commands
+### Specification Commands
+
+```bash
+# Create specifications
+fractary-faber spec create "My Specification"
+
+# Get specification
+fractary-faber spec get <id>
+
+# List specifications
+fractary-faber spec list
+
+# Update specification
+fractary-faber spec update <id> --title "Updated"
+
+# Validate specification
+fractary-faber spec validate <id>
+
+# Refine specification
+fractary-faber spec refine <id>
+
+# Delete specification
+fractary-faber spec delete <id>
+```
 
-| Category | Commands |
-|----------|----------|
-| **Workflow** | `run`, `status`, `pause`, `resume`, `recover`, `cleanup` |
-| **Work** | `issue`, `comment`, `label`, `milestone` |
-| **Repo** | `branch`, `commit`, `pr`, `tag`, `worktree` |
-| **Spec** | `create`, `get`, `list`, `validate`, `refine` |
-| **Logs** | `capture`, `stop`, `read`, `search`, `archive` |
+### Logs Commands
+
+```bash
+# Capture logs
+fractary-faber logs capture <workflow-id>
+
+# Stop capturing logs
+fractary-faber logs stop <session-id>
+
+# Write logs
+fractary-faber logs write --message "Log message"
+
+# Read logs
+fractary-faber logs read <session-id>
+
+# Search logs
+fractary-faber logs search --query "error"
+
+# List logs
+fractary-faber logs list
+
+# Archive logs
+fractary-faber logs archive --older-than 30
+
+# Delete logs
+fractary-faber logs delete <session-id>
+```
+
+## Configuration
+
+FABER is configured via `.fractary/faber/config.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "preset": "default",
+  "work": {
+    "provider": "github"
+  },
+  "repo": {
+    "provider": "github",
+    "defaultBranch": "main"
+  },
+  "spec": {
+    "directory": ".fractary/faber/specs"
+  },
+  "logs": {
+    "directory": ".fractary/faber/logs"
+  },
+  "workflow": {
+    "defaultAutonomy": "guarded",
+    "phases": ["frame", "architect", "build", "evaluate", "release"],
+    "checkpoints": true
+  },
+  "state": {
+    "directory": ".fractary/faber/state"
+  }
+}
+```
 
 ## Options
 
@@ -54,13 +224,96 @@ All commands support:
 - `--debug` - Enable debug output
 - `--help` - Show command help
 
-## Documentation
+## Authentication
+
+### GitHub App Authentication (Recommended)
+
+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
+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>
+export JIRA_API_TOKEN=<token>
+
+# Linear
+export LINEAR_API_KEY=<key>
+```
+
+## Architecture
 
-For complete documentation, see:
+See [SPEC-00026: Distributed Plugin Architecture](../specs/SPEC-00026-distributed-plugin-architecture.md)
 
-- **[Commands Reference](../docs/cli/commands.md)** - All commands
-- **[Authentication Guide](../docs/cli/authentication.md)** - GitHub App and PAT setup
-- **[Configuration Guide](../docs/guides/configuration.md)** - Configuration options
+The CLI follows SPEC-00026 standards:
+- Package: `@fractary/faber-cli`
+- Binary: `fractary-faber`
+- Located: `/cli` at root of repository
+- Depends on: `@fractary/faber` SDK
 
 ## License
 

package/dist/commands/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Config command - Read FABER configuration from unified config.yaml
+ *
+ * This command provides access to configuration values for scripts and tools.
+ * It uses the SDK's config loading logic, ensuring consistency across all tools.
+ */
+import { Command } from 'commander';
+export declare function createConfigCommand(): Command;
+//# sourceMappingURL=config.d.ts.map

package/dist/commands/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8BpC,wBAAgB,mBAAmB,IAAI,OAAO,CAkF7C"}

package/dist/commands/config.js

@@ -0,0 +1,106 @@
+/**
+ * Config command - Read FABER configuration from unified config.yaml
+ *
+ * This command provides access to configuration values for scripts and tools.
+ * It uses the SDK's config loading logic, ensuring consistency across all tools.
+ */
+import { Command } from 'commander';
+import { loadYamlConfig, configExists, getConfigPath, } from '../lib/yaml-config.js';
+/**
+ * Get a nested value from an object using dot notation
+ * @param obj The object to search
+ * @param path Dot-separated path (e.g., "faber.default_workflow")
+ * @returns The value at the path, or undefined if not found
+ */
+function getNestedValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+export function createConfigCommand() {
+    const configCmd = new Command('config')
+        .description('Manage FABER configuration');
+    configCmd
+        .command('get')
+        .description('Get configuration values')
+        .argument('[key]', 'Configuration key path (e.g., faber.default_workflow). Omit for full config.')
+        .option('--json', 'Output as JSON (default when no key specified)')
+        .option('--raw', 'Output raw value without quotes (for shell scripts)')
+        .action(async (key, options) => {
+        try {
+            // Check if config exists
+            if (!configExists()) {
+                const configPath = getConfigPath();
+                console.error(`Error: Configuration not found at ${configPath}`);
+                console.error('Run: fractary-core:init to create configuration');
+                process.exit(1);
+            }
+            // Load configuration using SDK logic
+            const config = loadYamlConfig({ warnMissingEnvVars: false });
+            if (!config) {
+                console.error('Error: Failed to load configuration');
+                process.exit(1);
+            }
+            // If no key specified, output full config
+            if (!key) {
+                console.log(JSON.stringify(config, null, options.json ? 2 : 0));
+                return;
+            }
+            // Get nested value
+            const value = getNestedValue(config, key);
+            if (value === undefined) {
+                if (options.raw) {
+                    // Output empty string for undefined (useful for shell scripts)
+                    console.log('');
+                }
+                else {
+                    console.log('null');
+                }
+                return;
+            }
+            // Output value
+            if (options.raw && typeof value === 'string') {
+                // Raw output - no quotes, no JSON
+                console.log(value);
+            }
+            else if (typeof value === 'object') {
+                // Objects are always JSON
+                console.log(JSON.stringify(value, null, options.json ? 2 : 0));
+            }
+            else if (options.json) {
+                // JSON output
+                console.log(JSON.stringify(value));
+            }
+            else {
+                // Default: string values without quotes, others as JSON
+                console.log(typeof value === 'string' ? value : JSON.stringify(value));
+            }
+        }
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
+            process.exit(1);
+        }
+    });
+    configCmd
+        .command('path')
+        .description('Show configuration file path')
+        .action(() => {
+        console.log(getConfigPath());
+    });
+    configCmd
+        .command('exists')
+        .description('Check if configuration file exists (exit 0 if yes, 1 if no)')
+        .action(() => {
+        process.exit(configExists() ? 0 : 1);
+    });
+    return configCmd;
+}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAMH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBpC;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAyKxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAMH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CA0KxC"}

package/dist/index.js

@@ -18,11 +18,12 @@ import { createInitCommand } from './commands/init.js';
 import { createMigrateCommand } from './commands/migrate.js';
 import { createPlanCommand } from './commands/plan/index.js';
 import { createAuthCommand } from './commands/auth/index.js';
+import { createConfigCommand } from './commands/config.js';
 // Force unbuffered output to prevent buffering issues in terminals
 if (process.stdout.isTTY) {
     process.stdout._handle?.setBlocking?.(true);
 }
-const version = '1.5.12';
+const version = '1.5.13';
 /**
  * Create and configure the main CLI program
  */
@@ -37,6 +38,7 @@ export function createFaberCLI() {
     // Workflow commands (top-level)
     program.addCommand(createInitCommand()); // init
     program.addCommand(createMigrateCommand()); // migrate
+    program.addCommand(createConfigCommand()); // config get/path/exists
     program.addCommand(createPlanCommand()); // plan
     program.addCommand(createRunCommand()); // workflow-run
     program.addCommand(createStatusCommand()); // run-inspect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fractary/faber-cli",
-  "version": "1.5.12",
+  "version": "1.5.13",
   "description": "FABER CLI - Command-line interface for FABER development toolkit",
   "main": "dist/index.js",
   "bin": {