@faros-fde-sandbox/cli 1.1.1 → 1.1.2

package/README.md

@@ -1,8 +1,34 @@
 # Faros CLI
 
 [![npm version](https://badge.fury.io/js/@faros-fde-sandbox%2Fcli.svg)](https://www.npmjs.com/package/@faros-fde-sandbox/cli)
-
-CLI for Faros AI - sync data, manage sources, view logs.
+[![Test](https://github.com/faros-fde/faros-cli/actions/workflows/test.yml/badge.svg)](https://github.com/faros-fde/faros-cli/actions/workflows/test.yml)
+
+CLI for Faros AI - sync test results, CI/CD events, and Linear data.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [faros sync tests](#faros-sync-tests)
+  - [faros sync ci-cd](#faros-sync-ci-cd)
+  - [faros sync linear](#faros-sync-linear)
+- [Configuration](#configuration)
+  - [Environment Variables](#environment-variables)
+  - [Configuration File](#configuration-file)
+  - [Configuration Priority](#configuration-priority)
+  - [CI/CD Environments](#cicd-environments)
+- [Global Options](#global-options)
+- [Validation](#validation)
+- [CI/CD Integration](#cicd-integration)
+  - [GitHub Actions](#github-actions)
+  - [Jenkins](#jenkins)
+  - [GitLab CI](#gitlab-ci)
+  - [CircleCI](#circleci)
+  - [Bitbucket Pipelines](#bitbucket-pipelines)
+- [URI Formats](#uri-formats)
+- [Development](#development)
+- [License](#license)
 
 ## Installation
 
@@ -24,20 +50,21 @@ faros sync ci-cd build \
   --commit "GitHub://myorg/myrepo/abc123" \
   --run "Jenkins://myorg/pipeline/456"
 
-# View logs
-faros logs
+# Report deployment status
+faros sync ci-cd deploy \
+  --status Success \
+  --commit "GitHub://myorg/myrepo/abc123" \
+  --deploy "Kubernetes://myapp/Prod/deploy-789"
 
-# List configured sources
-faros sources list
+# Sync Linear data
+faros sync linear \
+  --linear-api-key lin_api_xxx \
+  --cutoff-days 30
 ```
 
 ## Commands
 
-### `faros sync`
-
-Sync data from various sources to Faros.
-
-#### `faros sync tests`
+### `faros sync tests`
 
 Sync test results (JUnit, TestNG, xUnit, Cucumber, Mocha) to Faros.
 
@@ -56,7 +83,6 @@ faros sync tests <paths...> [options]
 - `--concurrency <number>` - Concurrent uploads (default: 8)
 - `--validate` - Validate only, don't send (fast, offline)
 - `--preview` - Show sample records
-- `--dry-run` - Sync to staging graph
 
 **Examples:**
 
@@ -67,24 +93,11 @@ faros sync tests test-results/*.xml \
   --commit "GitHub://myorg/myrepo/abc123"
 ```
 
-From S3:
-```bash
-faros sync tests s3://bucket/junit/ \
-  --pattern ".*\\.xml$" \
-  --s3-region us-east-1 \
-  --source "Jenkins"
-```
-
 Validate before syncing:
 ```bash
 faros sync tests *.xml --validate
 ```
 
-Dry run to staging:
-```bash
-faros sync tests *.xml --dry-run
-```
-
 #### `faros sync ci-cd`
 
 Sync CI/CD events (builds and deployments) to Faros.
@@ -114,88 +127,121 @@ faros sync ci-cd deploy \
   --deploy-end-time "2024-01-15T11:03:00Z"
 ```
 
-### `faros sources`
+### `faros sync linear`
+
+Sync Linear issues, projects, teams, and users to Faros.
+
+**Usage:**
+```bash
+faros sync linear --linear-api-key <key> [options]
+```
+
+**Options:**
+- `--linear-api-key <key>` - Linear API key (or set `LINEAR_API_KEY` env var)
+- `--cutoff-days <days>` - Fetch issues updated in the last N days (default: 90, or from config)
+- `--page-size <size>` - Number of records per API call, 1-250 (default: 50)
+- `--preview` - Show sync configuration without executing
 
-Manage data sources.
+**Configuration Priority:**
+1. CLI options (`--linear-api-key`, `--cutoff-days`)
+2. Environment variables (`LINEAR_API_KEY`, `FAROS_API_KEY`, `FAROS_GRAPH`)
+3. Config file (`faros.config.yaml`)
+4. Defaults
 
-**Commands:**
-- `faros sources list` - List all configured sources
-- `faros sources get <name>` - Get source details
+**Examples:**
 
-**Example:**
+Using environment variables (recommended):
 ```bash
-$ faros sources list
+export LINEAR_API_KEY=lin_api_xxx
+export FAROS_API_KEY=your_faros_key
+export FAROS_GRAPH=default
 
-Configured Sources:
+faros sync linear
+```
 
-┌────────┬────────┬────────┬────────────────────┐
-│ Source │ Type   │ Status │ Config             │
-├────────┼────────┼────────┼────────────────────┤
-│ linear │ Linear │ ✓      │ Configured         │
-│ github │ GitHub │ ✓      │ Configured         │
-│ s3     │ S3     │ ⚠      │ Missing credentials│
-└────────┴────────┴────────┴────────────────────┘
+Using CLI options:
+```bash
+faros sync linear \
+  --linear-api-key lin_api_xxx \
+  --graph default
 ```
 
-### `faros logs`
+Using config file (`faros.config.yaml`):
+```yaml
+# Never put API keys here - use environment variables!
+url: https://prod.api.faros.ai
+graph: default
+origin: my-company-ci
 
-View sync logs and debug information.
+sources:
+  linear:
+    cutoffDays: 30    # Fetch last 30 days
+    pageSize: 100     # Larger page size
+```
 
-**Usage:**
+Then run:
 ```bash
-faros logs [options]
+export LINEAR_API_KEY=lin_api_xxx
+faros sync linear
 ```
 
-**Options:**
-- `--level <level>` - Filter by log level (info, warn, error, debug)
-- `--since <time>` - Show logs since time (ISO-8601)
-- `--until <time>` - Show logs until time (ISO-8601)
-- `--out-file <path>` - Export logs to file
+Sync only recent issues (override config):
+```bash
+faros sync linear --cutoff-days 7
+```
 
-**Examples:**
+Preview configuration before syncing:
 ```bash
-# Recent logs
-faros logs
+faros sync linear --preview
+```
 
-# Error logs only
-faros logs --level error
+**What gets synced:**
+- **Teams** - All teams in your Linear workspace
+- **Projects** - All projects including leads and team assignments
+- **Issues** - Issues updated within the cutoff period (default: 90 days)
+- **Users** - All users in your workspace
 
-# Export logs
-faros logs --out-file sync-logs.json
+**Requirements:**
+- Docker must be running
+- Linear API key with read permissions
+- Faros API key and graph configured
 
-# Logs from specific time
-faros logs --since "2024-01-15T10:00:00Z"
-```
+**Notes:**
+- Issues are filtered by update date using the `--cutoff-days` parameter
+- The connector uses pagination to handle large datasets
+- All timestamps and relationships are preserved
 
 ## Configuration
 
 The CLI uses a two-file configuration approach:
 
-### 1. Credentials (`.env`)
+### Environment Variables
 
-Store sensitive credentials in a `.env` file (never commit this!):
+The CLI can be configured entirely through environment variables, which is ideal for CI/CD pipelines where `.env` files are not available.
 
-```bash
-# Required
-FAROS_API_KEY=your_faros_api_key_here
+#### Required Environment Variables
 
-# Optional overrides
-FAROS_URL=https://prod.api.faros.ai
-FAROS_GRAPH=default
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `FAROS_API_KEY` | Faros API key (required for all operations) | `your_faros_api_key_here` |
+| `LINEAR_API_KEY` | Linear API key (required for `faros sync linear`) | `lin_api_xxx` |
 
-# Data source credentials
-LINEAR_API_KEY=your_linear_api_key
-GITHUB_TOKEN=your_github_token
+#### Optional Faros Configuration
 
-# AWS credentials (for S3 test results)
-AWS_ACCESS_KEY_ID=your_aws_access_key
-AWS_SECRET_ACCESS_KEY=your_aws_secret_key
-AWS_REGION=us-east-1
-```
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `FAROS_URL` | Faros API URL | `https://prod.api.faros.ai` | `https://prod.api.faros.ai` |
+| `FAROS_GRAPH` | Target graph name | `default` | `my-graph` |
+| `FAROS_ORIGIN` | Origin identifier for synced data | - | `my-company-ci` |
+
+#### Logging and Debug
 
-See `.env.example` for a complete template.
+| Variable | Description | Values | Default |
+|----------|-------------|--------|---------|
+| `FAROS_LOG_LEVEL` | Log level | `debug`, `info`, `warn`, `error` | `info` |
+| `FAROS_DEBUG` | Enable debug mode | `true`, `false` | `false` |
 
-### 2. Configuration (`faros.config.yaml`)
+### Configuration File
 
 Store non-sensitive configuration in `faros.config.yaml`:
 
@@ -203,20 +249,8 @@ Store non-sensitive configuration in `faros.config.yaml`:
 # Faros API configuration
 url: https://prod.api.faros.ai
 graph: default
-stagingGraph: default-staging
 origin: my-company-ci
 
-# Data sources (credentials in .env)
-sources:
-  linear:
-    type: Linear
-    syncInterval: 1h
-    streams:
-      - issues
-      - projects
-      - teams
-      - users
-
 # Default values for commands
 defaults:
   testSource: Jenkins
@@ -237,6 +271,76 @@ Configuration is loaded in this order (highest priority first):
 
 **Config file search order**: `faros.config.yaml` → `faros.config.yml` → `faros.config.json` → `.farosrc.*`
 
+### CI/CD Environments
+
+In CI/CD pipelines where `.env` files cannot be used, configure the CLI entirely through environment variables stored as secrets in your CI/CD platform.
+
+#### Setting Up Environment Variables
+
+**GitHub Actions:**
+1. Go to repository Settings → Secrets and variables → Actions
+2. Add `FAROS_API_KEY` as a repository secret
+3. Reference in workflows using `${{ secrets.FAROS_API_KEY }}`
+
+**GitLab CI:**
+1. Go to Settings → CI/CD → Variables
+2. Add `FAROS_API_KEY` as a masked and protected variable
+3. Variables are automatically available in pipeline jobs
+
+**Jenkins:**
+1. Go to Credentials → System → Global credentials
+2. Add secret text with ID `faros-api-key`
+3. Reference using `credentials('faros-api-key')`
+
+**CircleCI:**
+1. Go to Project Settings → Environment Variables
+2. Add `FAROS_API_KEY`
+3. Variables are automatically available in jobs
+
+**Bitbucket Pipelines:**
+1. Go to Repository settings → Pipelines → Repository variables
+2. Add `FAROS_API_KEY` as a secured variable
+3. Variables are automatically available in pipeline steps
+
+#### Example: Minimal CI/CD Configuration
+
+For most CI/CD use cases, only `FAROS_API_KEY` is required:
+
+```bash
+# Set this as a secret in your CI/CD platform
+FAROS_API_KEY=your_api_key_here
+
+# Optional: Override defaults
+FAROS_GRAPH=production
+FAROS_URL=https://prod.api.faros.ai
+```
+
+Then in your pipeline:
+
+```bash
+# Environment variables are automatically picked up
+faros sync tests test-results/*.xml \
+  --source "Jenkins" \
+  --commit "GitHub://myorg/myrepo/$COMMIT_SHA"
+```
+
+#### Example: Full Configuration via Environment Variables
+
+For advanced setups, all configuration can be provided via environment variables:
+
+```bash
+# Required
+FAROS_API_KEY=your_api_key_here
+
+# Faros configuration
+FAROS_URL=https://prod.api.faros.ai
+FAROS_GRAPH=production
+FAROS_ORIGIN=github-actions
+
+# Logging
+FAROS_LOG_LEVEL=info
+```
+
 ## Global Options
 
 All commands support these global options:
@@ -249,9 +353,9 @@ All commands support these global options:
 - `--json` - Output JSON (for scripting)
 - `--no-color` - Disable colors
 
-## Dry Run & Validation
+## Validation
 
-The CLI supports three verification modes:
+The CLI supports two verification modes before syncing to production:
 
 ### 1. `--validate` (Fast, Offline)
 
@@ -273,28 +377,7 @@ Would create:
 Run without --validate to sync to Faros
 ```
 
-### 2. `--dry-run` (Full E2E, Staging Graph)
-
-Sync to a staging graph for full verification:
-
-```bash
-faros sync tests *.xml --dry-run
-```
-
-**Output:**
-```
-⚠ Dry-run mode: syncing to staging graph 'default-staging'
-
-Uploading |████████████████████| 100% | 24/24 suites
-
-✓ Synced 24 test suites to staging graph
-  Graph: default-staging
-  View in Faros: https://app.faros.ai/default-staging/qa
-
-To sync to production, run without --dry-run
-```
-
-### 3. `--preview` (Sample Preview)
+### 2. `--preview` (Sample Preview)
 
 Show sample records that would be created:
 
@@ -316,11 +399,25 @@ qa_TestExecution:
     "stats": { "passed": 45, "failed": 0 }
   }
 
-Run with --dry-run to sync to staging
+Run without --preview to sync to Faros
+```
+
+**Testing with Different Environments:**
+
+To sync to different environments or graphs, use the `FAROS_GRAPH` environment variable or the `-g/--graph` flag:
+
+```bash
+# Sync to staging graph
+FAROS_GRAPH=staging faros sync tests *.xml
+
+# Or use the flag
+faros sync tests *.xml --graph staging
 ```
 
 ## CI/CD Integration
 
+The Faros CLI integrates seamlessly with CI/CD platforms using environment variables. Store `FAROS_API_KEY` as a secret in your CI/CD platform and reference it in your pipeline configuration.
+
 ### GitHub Actions
 
 ```yaml
@@ -350,6 +447,12 @@ environment {
   FAROS_API_KEY = credentials('faros-api-key')
 }
 
+stage('Test') {
+  steps {
+    sh 'npm test'
+  }
+}
+
 stage('Sync Results') {
   steps {
     sh '''
@@ -359,6 +462,123 @@ stage('Sync Results') {
     '''
   }
 }
+
+stage('Report Build Status') {
+  steps {
+    sh '''
+      faros sync ci-cd build \
+        --status Success \
+        --commit "GitHub://org/repo/${GIT_COMMIT}" \
+        --run "Jenkins://org/pipeline/${BUILD_ID}"
+    '''
+  }
+}
+```
+
+### GitLab CI
+
+```yaml
+test:
+  stage: test
+  script:
+    - npm test
+  artifacts:
+    reports:
+      junit: test-results/*.xml
+
+sync_results:
+  stage: deploy
+  script:
+    - npm install -g @faros-fde-sandbox/cli
+    - |
+      faros sync tests test-results/*.xml \
+        --source "GitLab-CI" \
+        --commit "GitLab://${CI_PROJECT_PATH}/${CI_COMMIT_SHA}"
+  variables:
+    FAROS_API_KEY: $FAROS_API_KEY
+  when: always
+
+report_build:
+  stage: deploy
+  script:
+    - |
+      faros sync ci-cd build \
+        --status Success \
+        --commit "GitLab://${CI_PROJECT_PATH}/${CI_COMMIT_SHA}" \
+        --run "GitLab-CI://${CI_PROJECT_PATH}/${CI_PIPELINE_ID}"
+  variables:
+    FAROS_API_KEY: $FAROS_API_KEY
+```
+
+### CircleCI
+
+```yaml
+version: 2.1
+
+jobs:
+  test:
+    docker:
+      - image: cimg/node:18.0
+    steps:
+      - checkout
+      - run:
+          name: Run Tests
+          command: npm test
+      - store_test_results:
+          path: test-results
+      - run:
+          name: Sync Test Results to Faros
+          when: always
+          command: |
+            npx @faros-fde-sandbox/cli sync tests test-results/*.xml \
+              --source "CircleCI" \
+              --commit "GitHub://${CIRCLE_PROJECT_USERNAME}/${CIRCLE_PROJECT_REPONAME}/${CIRCLE_SHA1}"
+          environment:
+            FAROS_API_KEY: ${FAROS_API_KEY}
+      - run:
+          name: Report Build Status
+          command: |
+            npx @faros-fde-sandbox/cli sync ci-cd build \
+              --status Success \
+              --commit "GitHub://${CIRCLE_PROJECT_USERNAME}/${CIRCLE_PROJECT_REPONAME}/${CIRCLE_SHA1}" \
+              --run "CircleCI://${CIRCLE_PROJECT_USERNAME}/${CIRCLE_PROJECT_REPONAME}/${CIRCLE_BUILD_NUM}"
+          environment:
+            FAROS_API_KEY: ${FAROS_API_KEY}
+
+workflows:
+  test-and-sync:
+    jobs:
+      - test
+```
+
+### Bitbucket Pipelines
+
+```yaml
+pipelines:
+  default:
+    - step:
+        name: Test
+        script:
+          - npm test
+        artifacts:
+          - test-results/**
+    - step:
+        name: Sync Results to Faros
+        script:
+          - npm install -g @faros-fde-sandbox/cli
+          - |
+            faros sync tests test-results/*.xml \
+              --source "Bitbucket-Pipelines" \
+              --commit "Bitbucket://${BITBUCKET_REPO_FULL_NAME}/${BITBUCKET_COMMIT}"
+          - |
+            faros sync ci-cd build \
+              --status Success \
+              --commit "Bitbucket://${BITBUCKET_REPO_FULL_NAME}/${BITBUCKET_COMMIT}" \
+              --run "Bitbucket-Pipelines://${BITBUCKET_REPO_FULL_NAME}/${BITBUCKET_BUILD_NUMBER}"
+        condition:
+          changesets:
+            includePaths:
+              - "**"
 ```
 
 ## URI Formats
@@ -413,6 +633,77 @@ npm test
 npm run lint
 ```
 
+### Testing
+
+The CLI has comprehensive test coverage to ensure reliability:
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage report
+npm run test:coverage
+
+# Run tests with UI
+npm run test:ui
+```
+
+**Test Structure:**
+- `src/**/*.test.ts` - Unit and integration tests alongside source files
+- `test/fixtures/` - Sample test result files for various formats
+- `test/utils/` - Test utilities and helpers
+
+**Coverage Thresholds:**
+- Core modules (config, API client, logger): >80% coverage
+- Critical paths enforce per-file thresholds
+- Overall project: >25% (command handlers require E2E testing)
+
+**What's Tested:**
+- ✅ Configuration loading and priority (CLI > env > file > defaults)
+- ✅ API client with retry logic and error handling
+- ✅ Logger with redaction of sensitive data
+- ✅ Test result parsing (JUnit, TestNG, xUnit, Cucumber, Mocha)
+- ✅ CI/CD event creation and validation
+- ✅ URI format validation
+- ✅ Validation and preview modes
+
+**Continuous Integration:**
+Tests run automatically on every push and pull request via GitHub Actions. Coverage reports are uploaded to Codecov.
+
+**Test Result Syncing:**
+Test results are automatically synced to Faros AI after every test run on the `main` branch. This provides observability into test health, trends, and failures over time. Results are synced using the CLI itself:
+
+```bash
+faros sync tests test-results/junit.xml \
+  --source "GitHub-Actions" \
+  --type "Unit" \
+  --commit "GitHub://faros-fde/faros-cli/$COMMIT_SHA"
+```
+
+View synced test results in the Faros UI under the `qa_TestExecution` model.
+
+### End-to-End Testing
+
+E2E tests validate the full CLI workflow by actually syncing test results to Faros AI.
+
+**Run E2E tests:**
+
+```bash
+# Run E2E tests
+FAROS_API_KEY=xxx ./scripts/e2e-test-sync.sh
+```
+
+**What's tested:**
+- ✅ Parsing test result files (JUnit, TestNG, Mocha)
+- ✅ Data validation and transformation
+- ✅ API communication with Faros
+- ✅ Error handling and reporting
+
+**See the full guide:** [docs/e2e-testing.md](docs/e2e-testing.md)
+
 ### Publishing
 
 See [PUBLISHING.md](PUBLISHING.md) for instructions on publishing new versions to npm.

package/lib/commands/sync/ci-cd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ci-cd.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/ci-cd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAoJ5C,wBAAgB,eAAe,IAAI,OAAO,CAqDzC"}
+{"version":3,"file":"ci-cd.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/ci-cd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgHpC,wBAAgB,eAAe,IAAI,OAAO,CAmDzC"}