# ⚡ BFD CLI - Black Flag Feedback Management

Command-line interface for managing feedback in the Black Flag Feedback Management Platform.

## Installation

### For End Users (NPM Package)

Install globally from NPM:

```bash
npm install -g @black-flag-design/bfd-cli
```

Then use the `bfd` command from anywhere:

```bash
bfd --help
bfd get --from 24h
```

**NPM Package:** https://www.npmjs.com/package/@black-flag-design/bfd-cli

### For Development (Local)

From the project root:

```bash
cd bfd-cli
npm install
```

## Authentication Setup

Add these environment variables to your `.env` file:

```bash
BF_PROJECT_ID=your_project_public_key_here
BF_PROJECT_SECRET=your_project_secret_here
```

These credentials authenticate your CLI access to the feedback system.

## Usage

### If Installed Globally (Recommended)

```bash
bfd <command> [options]
```

### From Project Root (Development)

```bash
npm run bfd -- <command> [options]
```

### From BFD CLI Directory (Development)

```bash
cd bfd-cli
npm run cli -- <command> [options]
```

## Commands

### Get Feedback

Retrieve feedback with optional date range filtering. Each feedback item includes all associated data including AI-generated computed properties when available.

```bash
# Get all feedback
npm run bfd -- get

# Get feedback from last 7 days
npm run bfd -- get --from 7d

# Get feedback from last 24 hours
npm run bfd -- get --from 24h

# Get feedback between date ranges
npm run bfd -- get --from 30d --to 7d
```

**Date Format Examples:**
- `24h` - Last 24 hours
- `7d` - Last 7 days
- `3w` - Last 3 weeks
- `2m` - Last 2 months

**Response Includes:**
- Complete feedback data (text, status, severity, URL, etc.)
- Project and client information
- Screenshots and audio attachments
- Linear and Notion sync status
- **AI-generated computed properties** (screenshot analysis, navigation context, technical synthesis) when available
- Console entries and click trail
- Tags and assignments
- Metadata and timestamps

### Update Feedback

Update specific fields of a feedback entry:

```bash
# Update status
npm run bfd -- update <feedback-id> --status "In Progress"

# Update severity
npm run bfd -- update <feedback-id> --severity major

# Update multiple fields
npm run bfd -- update <feedback-id> \
  --status Done \
  --severity minor \
  --text "Updated description"

# Assign to user
npm run bfd -- update <feedback-id> --assigned-to <user-id>

# Add Linear integration data
npm run bfd -- update <feedback-id> \
  --linear-issue-id ISS-123 \
  --linear-issue-number 123

# Add metadata
npm run bfd -- update <feedback-id> \
  --metadata '{"priority": "high", "tags": ["bug", "urgent"]}'
```

**Available Fields:**
- `--status` - Backlog, Todo, In Progress, In Review, Done, Canceled, Duplicate
- `--severity` - none, minor, major
- `--text` - Feedback text content
- `--assigned-to` - User ID to assign
- `--linear-issue-id` - Linear issue identifier
- `--linear-issue-number` - Linear issue number
- `--linear-team-id` - Linear team ID
- `--linear-state-id` - Linear state ID
- `--notion-page-id` - Notion page ID
- `--notion-page-url` - Notion page URL
- `--metadata` - JSON metadata object

### Create Feedback

Create a new feedback entry:

```bash
# Create text feedback (minimum required)
npm run bfd -- create \
  --kind text \
  --url "https://example.com/page" \
  --text "Bug found on login page"

# Create with full details
npm run bfd -- create \
  --kind text \
  --url "https://example.com" \
  --text "Button not working" \
  --status Todo \
  --severity major \
  --page-url "https://example.com/login" \
  --assigned-to <user-id>

# Create location feedback
npm run bfd -- create \
  --kind location \
  --url "https://example.com" \
  --selector "#submit-button" \
  --text "Submit button unresponsive"

# Create with metadata
npm run bfd -- create \
  --kind text \
  --url "https://example.com" \
  --text "Feature request" \
  --metadata '{"source": "customer", "priority": "high"}'
```

**Required Fields:**
- `--kind` - text, voice, location, document
- `--url` - URL where feedback was submitted

**Optional Fields:**
- `--text` - Feedback content
- `--status` - Initial status (default: Backlog)
- `--severity` - Severity level (default: none)
- `--page-url` - Specific page URL
- `--selector` - CSS selector for location
- `--user-agent` - User agent string
- `--viewport` - Viewport dimensions
- `--assigned-to` - User ID
- `--metadata` - JSON metadata

### Generate Cursor Rules

Generate comprehensive Cursor rules documentation for BFD CLI **AND** generic dev culture principles:

```bash
# Generate ALL rules (BFD CLI + Dev Culture principles)
npm run bfd -- generate-rules

# Generate only BFD CLI documentation
npm run bfd -- generate-rules --bfd-only

# Generate only Dev Culture principles
npm run bfd -- generate-rules --dev-culture-only

# Generate to custom location
npm run bfd -- generate-rules --output custom/path/to/rules
```

**What Gets Generated:**

#### 📦 BFD CLI Documentation (3 files)
1. **bfd-cli/README.mdc** - Quick reference for daily use
2. **bfd-cli/bfd-cli-guide.mdc** - Complete command documentation
3. **bfd-cli/agent-workflow.mdc** - AI agent workflow guide

#### 🎯 Dev Culture Principles (11 files)
**Generic coding principles that apply to any similar tech stack:**

**Culture Rules:**
- `culture/single-implementation-principle.mdc` - Zero tolerance for dual implementations
- `culture/no-mock-data.mdc` - Prohibition of fake/placeholder data
- `culture/backward-compatibility-kills-companies.mdc` - Steve Jobs principle
- `culture/no-duplicate-files.mdc` - No file suffixes (`.fixed.ts`, `.v2.ts`)
- `culture/proof-driven-communication.mdc` - Evidence-based completion claims

**Architecture Rules:**
- `architecture/backend/separation-of-concerns.mdc` - Layer responsibilities (controllers/models/services)
- `architecture/frontend/component-composition.mdc` - React composition patterns

**File-Scoped Rules:**
- `file-scoped/frontend/component-directory-enforcement.mdc` - Organized component structure
- `file-scoped/database/drizzle-orm.mdc` - Drizzle ORM patterns

**TypeScript Rules:**
- `typescript/strict-typing.mdc` - Zero tolerance for `any` types

**Tech-Ops Rules:**
- `tech-ops/scripting/script-standards.mdc` - Never-hanging scripts with timeout failsafes

**Total: 14 rule files covering BFD CLI + generic development principles**

**When to Use:**

- Setting up new development environments with your team's coding standards
- Onboarding team members or AI agents with consistent principles
- After CLI updates or when establishing new projects
- Sharing project setup with collaborators
- Bootstrapping similar projects with the same tech stack (React, Express, Drizzle, TypeScript)

**Directory Handling:**

- Creates directories recursively if they don't exist
- Handles both relative and absolute paths
- Replaces existing files if exact path matches
- Default location: `.cursor/rules/`

## Output Format

The CLI outputs feedback in a structured text format optimized for AI agent consumption:

```
Found 2 feedback item(s):
════════════════════════════════════════════════════════════════════════════════

FEEDBACK ID: abc123
PROJECT: My Project (My Organization)
KIND: text
STATUS: Backlog
SEVERITY: minor
URL: https://example.com
TEXT: Button not working properly
CREATED: 2025-01-15T10:30:00.000Z
UPDATED: 2025-01-15T10:30:00.000Z
────────────────────────────────────────────────────────────────────────────────
```

## Troubleshooting

### Authentication Errors

If you see "Missing required environment variables":

1. Check your `.env` file has `BF_PROJECT_ID` and `BF_PROJECT_SECRET`
2. Ensure you're running from project root or bfd-cli directory
3. Verify credentials are correct (get them from your project settings)

### Connection Errors

If you see "API request failed":

1. Check server is running: `npm run dev`
2. Verify `BFD_API_URL` environment variable (defaults to https://foundry.blackflag.design)
3. Check network connectivity

### Invalid Date Format

If you see "Invalid date format":

Use relative format: `7d` (days), `24h` (hours), `3w` (weeks), `2m` (months)

## Environment Variables

- `BF_PROJECT_ID` - **Required** - Your project's public key
- `BF_PROJECT_SECRET` - **Required** - Your project's secret key
- `BFD_API_URL` - Optional - API base URL (default: https://foundry.blackflag.design)

## Development

```bash
# Install dependencies
npm install

# Run CLI directly
npm run cli -- get

# TypeScript compilation
npx tsc --noEmit
```

## Architecture

- `cli.ts` - Main CLI entry point using Commander.js
- `commands/` - Command implementations (get, update, create)
- `lib/auth.ts` - Authentication helper
- `lib/api-client.ts` - HTTP client with timeout failsafes
- `lib/formatters.ts` - Output formatting utilities

## Support

For issues or questions, refer to the main project documentation in `.cursor/rules/bfd-cli/`.

---

**Note:** This package was previously published as `@black-flag-design/starforge`. The new package name is `@black-flag-design/bfd-cli` with the command `bfd`.