@testcollab/cli 1.3.0

package/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: main
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - name: Bump version
+        if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'release'
+        run: node scripts/bump-version.js
+      - name: upgrade npm
+        run: npm i -g npm@latest
+        
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+
+
+      - name: Publish to npm
+        if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'release'
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/DEVELOPMENT.md

@@ -0,0 +1,225 @@
+# Development Guide
+
+Guide for contributing to the TestCollab CLI.
+
+## Setup
+
+```bash
+git clone https://github.com/TCSoftInc/testcollab-cli.git
+cd testcollab-cli
+npm install
+```
+
+### Make the CLI available globally (for testing)
+
+```bash
+npm link          # creates global 'tc' symlink to your local code
+npm unlink -g testcollab-cli  # undo when done
+```
+
+## Running locally
+
+You don't need to install the package to test changes. Run directly with Node:
+
+```bash
+# From the tc-cli directory
+node src/index.js sync --project 123
+node src/index.js createTestPlan --api-key $TOKEN --project 123 ...
+node src/index.js report --api-key $TOKEN --project 123 ...
+node src/index.js specgen --src ../my-app/src --out ../my-app/features
+```
+
+Or use `npm link` (see above) and run `tc` from anywhere.
+
+## Environment variables
+
+```bash
+# Required for sync
+export TESTCOLLAB_TOKEN=your_api_token
+
+# Required for specgen (pick one)
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_GENAI_API_KEY=...
+
+# Optional: point at a different API
+export API_URL=http://localhost:1337  # or use --api-url flag
+```
+
+## Project structure
+
+```
+tc-cli/
+├── src/
+│   ├── index.js                  # CLI entry point (Commander.js)
+│   ├── commands/
+│   │   ├── featuresync.js        # tc sync
+│   │   ├── createTestPlan.js     # tc createTestPlan
+│   │   ├── report.js             # tc report
+│   │   └── specgen.js            # tc specgen
+│   └── ai/
+│       └── discovery.js          # AI-powered source code analysis for specgen
+├── tests/
+│   ├── README.md                 # Testing strategy docs
+│   ├── utils/                    # Test helpers (git, API mocks, builders)
+│   └── scenarios/                # Test scenarios per feature
+├── samples/
+│   └── reports/                  # Sample Mochawesome & JUnit files
+├── docs/
+│   └── specgen.md                # Specgen design notes
+├── .github/workflows/
+│   └── release.yml               # CI/CD pipeline
+└── package.json
+```
+
+## Key technical decisions
+
+### ES Modules
+
+The package uses `"type": "module"`. This means:
+
+- Use `import` / `export`, not `require()`
+- File extensions are required in imports (e.g., `./commands/featuresync.js`)
+- `__dirname` is not available — use `import.meta.url` instead
+
+### Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `commander` | CLI argument parsing |
+| `simple-git` | Git operations (diff, log, status) |
+| `@cucumber/gherkin` | Gherkin `.feature` file parsing |
+| `@anthropic-ai/sdk` | Claude AI for specgen |
+| `@google/generative-ai` | Gemini AI for specgen |
+| `testcollab-sdk` | TestCollab API client (createTestPlan, report) |
+| `testcollab-cypress-plugin` | Shared result upload logic (report) |
+
+## Testing
+
+```bash
+# Run all tests
+npm test
+
+# Run a specific test file
+npm test tests/scenarios/initial-sync.test.js
+
+# Watch mode
+npm test -- --watch
+
+# Coverage report
+npm test -- --coverage
+```
+
+Tests use **real Git repositories** (created in temp dirs) with **mocked network calls**. See `tests/README.md` for the full testing strategy.
+
+### Creating test scenarios
+
+Use the test utilities in `tests/utils/`:
+
+- `git-helpers.js` — Create temp Git repos, add/modify/delete files, commit
+- `api-mocks.js` — Mock TestCollab API responses
+- `scenario-builders.js` — Build complex test scenarios
+
+## How each command works
+
+### `tc sync` (featuresync.js)
+
+1. Validates Git repo and `TESTCOLLAB_TOKEN`
+2. Calls `GET /bdd/sync?project=<id>` to get the last synced commit
+3. Runs `git diff --find-renames` between last sync and HEAD
+4. Parses changed `.feature` files with `@cucumber/gherkin`
+5. Computes SHA-1 hashes for features and scenarios
+6. Calls `POST /bdd/resolve-ids` to map old hashes to existing TestCollab IDs
+7. Builds a `GherkinSyncDelta` payload and POSTs to `POST /bdd/sync`
+
+Key details:
+- Rename detection: `R100` = pure rename, `R097` = rename + content change
+- Hash-based matching with title fallback for ID resolution
+- Handles deleted scenarios within modified files
+
+### `tc createTestPlan` (createTestPlan.js)
+
+1. Validates project, tag, and assignee exist
+2. Creates a test plan named `CI Test: DD-MM-YYYY HH:MM`
+3. Bulk-adds test cases matching the CI tag
+4. Assigns the plan to the specified user
+5. Writes plan ID to `tmp/tc_test_plan`
+
+### `tc report` (report.js)
+
+1. Validates API key, project, and test plan
+2. Parses the result file based on `--format`:
+   - **Mochawesome**: Walks nested suites, extracts test titles and results
+   - **JUnit**: Parses XML `<testcase>` elements
+3. Extracts TestCollab case IDs from test names (patterns: `[TC-123]`, `TC-123`, `id-123`, `testcase-123`)
+4. Optionally extracts configuration IDs (`config-id-<id>`, `config-<id>`)
+5. Maps results: pass → 1, fail → 2, skip → 3
+6. Uploads results to the test plan via TestCollab API
+
+### `tc specgen` (specgen.js + ai/discovery.js)
+
+1. Scans source directory for `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` files
+2. Sends file summaries to AI for **discovery** — identifies target families and targets
+3. Caches discovery results in `.testcollab/specgen.json`
+4. For each target, generates a `.feature` file with 2-4 scenarios using structured AI output
+5. Falls back to a template feature if AI generation fails
+
+## Debugging
+
+### Add debug logging
+
+```javascript
+// Temporary — add anywhere in command files
+console.log('Debug:', JSON.stringify(payload, null, 2));
+```
+
+### Test with a scratch repo
+
+```bash
+mkdir /tmp/test-repo && cd /tmp/test-repo
+git init && git config user.email "test@test.com" && git config user.name "Test"
+
+mkdir -p features/auth
+cat > features/auth/login.feature << 'EOF'
+Feature: Login
+  Scenario: Valid credentials
+    Given the user is on the login page
+    When they enter valid credentials
+    Then they should see the dashboard
+EOF
+
+git add . && git commit -m "Initial"
+node /path/to/tc-cli/src/index.js sync --project 123
+```
+
+### Mock the API
+
+```javascript
+global.fetch = jest.fn().mockResolvedValue({
+  ok: true,
+  json: () => Promise.resolve({ lastSyncedCommit: null }),
+});
+```
+
+## Publishing
+
+```bash
+# 1. Dry-run to check what gets published
+npm pack
+
+# 2. Bump version
+npm version patch -m "release %s"   # or minor / major
+
+# 3. Publish
+npm publish
+
+# 4. Push tags
+git push --follow-tags
+```
+
+The GitHub Actions workflow (`.github/workflows/release.yml`) also handles automated publishing on release creation.
+
+### What gets published
+
+Controlled by `.npmignore`:
+- **Included:** `src/`, `samples/`, `package.json`, `README.md`, `LICENSE`
+- **Excluded:** `tests/`, `DEV_NOTES.md`, `debug-*.js`, `.env`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 TestCollab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,378 @@
+# TestCollab CLI
+
+Command-line tools for syncing Gherkin feature files, running test plans, and uploading results to [TestCollab](https://testcollab.com).
+
+```
+npm install -g testcollab-cli
+```
+
+## Quick Start
+
+Upload test results to TestCollab from your CI pipeline in two steps:
+
+```bash
+export TESTCOLLAB_TOKEN=your_token_here
+
+# Step 1: Create a test plan with your CI-tagged cases
+tc createTestPlan --project 123 --ci-tag-id 456 --assignee-id 789
+
+# Step 2: After running your tests, upload results
+tc report --project 123 --test-plan-id 555 --format junit --result-file ./results.xml
+```
+
+Or sync BDD feature files to TestCollab:
+
+```bash
+tc sync --project 123
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| [`tc createTestPlan`](#tc-createtestplan) | Create a test plan and assign tagged cases |
+| [`tc report`](#tc-report) | Upload Mochawesome or JUnit results |
+| [`tc sync`](#tc-sync) | Sync `.feature` files from Git to TestCollab (designed for CI/CD, works locally too) |
+
+The most common workflow is **createTestPlan → run your tests → report** to automatically upload test results from CI/CD.
+
+---
+
+### `tc createTestPlan`
+
+Creates a test plan, adds all test cases matching a CI tag, and assigns it to a user. Designed for CI pipelines where you want to automatically create a plan before running tests.
+
+```bash
+tc createTestPlan \
+  --project <id> \
+  --ci-tag-id <id> \
+  --assignee-id <id> \
+  [--api-key <key>] \
+  [--api-url <url>]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--project <id>` | Yes | Project ID |
+| `--ci-tag-id <id>` | Yes | Tag ID — test cases with this tag are added to the plan |
+| `--assignee-id <id>` | Yes | User ID to assign the plan execution to |
+| `--api-key <key>` | No | TestCollab API key (or set `TESTCOLLAB_TOKEN` env var) |
+| `--api-url <url>` | No | API base URL (default: `https://api.testcollab.io`). Use `https://api-eu.testcollab.io` for EU region. |
+
+**Output:** Writes the created plan ID to `tmp/tc_test_plan` as `TESTCOLLAB_TEST_PLAN_ID=<id>`. You can source this file in subsequent CI steps.
+
+---
+
+### `tc report`
+
+Parses a test result file (Mochawesome JSON or JUnit XML) and uploads results to a TestCollab test plan.
+
+```bash
+tc report \
+  --project <id> \
+  --test-plan-id <id> \
+  --format <mochawesome|junit> \
+  --result-file <path> \
+  [--api-key <key>] \
+  [--api-url <url>]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--project <id>` | Yes | Project ID |
+| `--test-plan-id <id>` | Yes | Test plan to attach results to |
+| `--format <type>` | Yes | `mochawesome` or `junit` |
+| `--result-file <path>` | Yes | Path to the result file |
+| `--api-key <key>` | No | TestCollab API key (or set `TESTCOLLAB_TOKEN` env var) |
+| `--api-url <url>` | No | API base URL override (default: `https://api.testcollab.io`). Use `https://api-eu.testcollab.io` for EU region. |
+
+#### Mapping test cases
+
+Your test names must include a TestCollab case ID so results can be matched. Any of these patterns work:
+
+```
+[TC-123] Login should succeed          ← bracketed
+TC-123 Login should succeed            ← prefix
+Login should succeed id-123            ← id- prefix
+Login should succeed testcase-123      ← testcase- prefix
+```
+
+#### Configuration-specific runs
+
+If your test plan uses multiple configurations, include the config ID in your test names:
+
+- **Mochawesome:** Use `config-id-<id>` as a top-level suite title
+- **JUnit:** Include `config-id-<id>` or `config-<id>` in the test case name or classname
+
+#### Sample files
+
+See `samples/reports/` for example Mochawesome and JUnit files you can reference.
+
+#### Supported frameworks
+
+Any framework that can produce **Mochawesome JSON** or **JUnit XML** works with `tc report`. Here's how popular frameworks generate compatible output:
+
+| Framework | How to get compatible output | `--format` |
+|-----------|------------------------------|------------|
+| **Cypress** | `mochawesome` reporter (built-in plugin) | `mochawesome` |
+| **Playwright** | `--reporter=junit` | `junit` |
+| **Jest** | `jest-junit` package | `junit` |
+| **Pytest** | `--junitxml=results.xml` (built-in) | `junit` |
+| **TestNG** | Generates JUnit-compatible XML | `junit` |
+| **JUnit 4/5** | Native JUnit XML output | `junit` |
+| **Robot Framework** | `--xunit output.xml` | `junit` |
+| **PHPUnit** | `--log-junit results.xml` (built-in) | `junit` |
+| **Cucumber.js** | JUnit formatter plugin | `junit` |
+| **Cucumber JVM** | JUnit XML via built-in plugin | `junit` |
+| **WebDriverIO** | `@wdio/junit-reporter` | `junit` |
+| **TestCafe** | `testcafe-reporter-junit` | `junit` |
+| **Newman (Postman)** | `newman-reporter-junit` | `junit` |
+| **Behave** | `--junit` flag (built-in) | `junit` |
+| **Go (`go test`)** | `go-junit-report` | `junit` |
+| **Kaspresso / Kotlin** | JUnit XML (inherits from JUnit runner) | `junit` |
+
+For detailed setup instructions per framework, see [Framework Setup Guide](docs/frameworks.md).
+
+---
+
+### `tc sync`
+
+Synchronizes Gherkin `.feature` files from your Git repository with TestCollab. Features become test suites, scenarios become test cases. Designed to run in CI/CD pipelines (on push to main), but works locally too — it uses Git commit hashes to track what's already been synced.
+
+```bash
+tc sync --project <id> [--api-key <key>] [--api-url <url>]
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--project <id>` | Yes | TestCollab project ID |
+| `--api-key <key>` | No | TestCollab API key (or set `TESTCOLLAB_TOKEN` env var) |
+| `--api-url <url>` | No | API base URL (default: `https://api.testcollab.io`). Use `https://api-eu.testcollab.io` for EU region. |
+
+#### How it works
+
+1. Detects which `.feature` files changed since the last sync (using `git diff`)
+2. Parses the Gherkin and calculates content hashes
+3. Sends only the changes to TestCollab (creates, updates, renames, or deletes)
+
+Only **committed** files are synced. Uncommitted changes are ignored (with a warning).
+
+#### Example output
+
+```
+🔍 Fetching sync state from TestCollab...
+📊 Last synced commit: a1b2c3d4
+📊 Current HEAD commit: e5f6g7h8
+📄 Found 3 change(s)
+🚀 Syncing with TestCollab...
+
+📊 Synchronization Results:
+✨ Created 1 test case(s)
+🔄 Updated 2 test case(s)
+🔄 Renamed 1 suite(s)
+
+✅ Synchronization completed successfully
+```
+
+#### Try it with a sample project
+
+Fork [testcollab-bdd-demo](https://github.com/TCSoftInc/testcollab-bdd-demo) and run `tc sync` to see how it works before integrating with your own project.
+
+---
+
+## Authentication
+
+All commands authenticate the same way. Provide your API key using **either** method:
+
+1. **`--api-key` flag** (takes precedence)
+2. **`TESTCOLLAB_TOKEN` environment variable** (recommended for CI/CD)
+
+**Getting your API token:** Go to TestCollab → Account Settings → API Tokens.
+
+**EU region:** If your TestCollab account is hosted in the EU, pass `--api-url https://api-eu.testcollab.io` to all commands.
+
+### Setting the token
+
+```bash
+# macOS / Linux
+export TESTCOLLAB_TOKEN=your_token_here
+
+# Windows (Command Prompt)
+set TESTCOLLAB_TOKEN=your_token_here
+
+# Windows (PowerShell)
+$env:TESTCOLLAB_TOKEN = "your_token_here"
+```
+
+---
+
+## CI/CD Integration
+
+The most common use case is uploading test results from CI: create a test plan, run your tests, then report results back to TestCollab.
+
+### GitHub Actions
+
+#### Upload test results (create plan + run tests + report)
+
+```yaml
+name: Test Pipeline
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      TESTCOLLAB_TOKEN: ${{ secrets.TESTCOLLAB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - run: npm install -g testcollab-cli && npm ci
+
+      # Step 1: Create test plan with CI-tagged cases
+      - run: |
+          tc createTestPlan \
+            --project ${{ secrets.TC_PROJECT_ID }} \
+            --ci-tag-id ${{ secrets.TC_CI_TAG_ID }} \
+            --assignee-id ${{ secrets.TC_ASSIGNEE_ID }}
+
+      # Step 2: Read the created test plan ID
+      - run: cat tmp/tc_test_plan >> $GITHUB_ENV
+
+      # Step 3: Run your tests (example: Cypress)
+      - run: npx cypress run --reporter mochawesome
+
+      # Step 4: Upload results to TestCollab
+      - run: |
+          tc report \
+            --project ${{ secrets.TC_PROJECT_ID }} \
+            --test-plan-id $TESTCOLLAB_TEST_PLAN_ID \
+            --format mochawesome \
+            --result-file ./mochawesome-report/mochawesome.json
+```
+
+#### Sync feature files (on .feature file changes)
+
+If you use BDD and want to keep TestCollab in sync with your `.feature` files:
+
+```yaml
+name: Sync Feature Files
+on:
+  push:
+    branches: [main]
+    paths: ['**/*.feature']
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history required for accurate diffs
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - run: npm install -g testcollab-cli
+
+      - run: tc sync --project ${{ secrets.TC_PROJECT_ID }}
+        env:
+          TESTCOLLAB_TOKEN: ${{ secrets.TESTCOLLAB_TOKEN }}
+```
+
+> **Important:** `tc sync` requires `fetch-depth: 0` so it can compute accurate diffs against the last synced commit.
+
+### GitLab CI
+
+#### Upload test results
+
+```yaml
+test-and-report:
+  stage: test
+  image: node:22
+  variables:
+    TESTCOLLAB_TOKEN: $TESTCOLLAB_TOKEN
+  before_script:
+    - npm install -g testcollab-cli && npm ci
+  script:
+    - tc createTestPlan --project $TC_PROJECT_ID --ci-tag-id $TC_CI_TAG_ID --assignee-id $TC_ASSIGNEE_ID
+    - export $(cat tmp/tc_test_plan)
+    - npx cypress run --reporter mochawesome
+    - tc report --project $TC_PROJECT_ID --test-plan-id $TESTCOLLAB_TEST_PLAN_ID --format mochawesome --result-file ./mochawesome-report/mochawesome.json
+```
+
+#### Sync feature files
+
+```yaml
+sync-features:
+  stage: test
+  image: node:22
+  before_script:
+    - npm install -g testcollab-cli
+  script:
+    - tc sync --project $TC_PROJECT_ID
+  variables:
+    TESTCOLLAB_TOKEN: $TESTCOLLAB_TOKEN
+  only:
+    changes:
+      - "**/*.feature"
+```
+
+---
+
+## Troubleshooting
+
+### Common errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `TESTCOLLAB_TOKEN environment variable is not set` | Missing token | Set the env var (see [Authentication](#authentication)) |
+| `Not in a Git repository` | CLI run outside a Git repo | Run from inside a Git repository |
+| `Failed to fetch sync state: 404` | Wrong project ID | Check the project ID in TestCollab |
+| `409 Conflict` | Repo state changed since last sync | `git pull` and retry |
+| `Could not process features/x.feature` | Gherkin syntax error | Fix the `.feature` file syntax |
+
+### Tips
+
+- **Commit before syncing** — Only committed `.feature` files are synced
+- **Sync often** — Smaller changesets are easier to review
+- **Use CI** — Automate sync on push so your test cases are always current
+- **Test first** — Try sync on a dev project before pointing at production
+- **Large repos** — The CLI only processes changed files, so performance scales with changes, not repo size. Keep individual syncs under 6MB.
+
+---
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+- Git 2.0 or higher
+
+## Installation options
+
+```bash
+# Global (recommended)
+npm install -g testcollab-cli
+tc sync --project 123
+
+# Local (per-project)
+npm install testcollab-cli --save-dev
+npx tc sync --project 123
+```
+
+## Links
+
+- [TestCollab](https://testcollab.com)
+- [Documentation](https://help.testcollab.com)
+- [Sample BDD project](https://github.com/TCSoftInc/testcollab-bdd-demo)
+- [Report a bug](https://github.com/TCSoftInc/testcollab-cli/issues)
+- [Support](mailto:support@testcollab.com)
+
+## License
+
+MIT