ado-sync 0.1.65 → 0.1.67

package/docs/agent-setup.md

@@ -1,204 +0,0 @@
-# Agent Setup Guide
-
-This document is written for AI agents (Claude Code, GitHub Copilot, Cursor, etc.) to autonomously set up `ado-sync` for a user. Follow the steps in order.
-
----
-
-## Step 1 — Detect the test framework
-
-Scan the user's repository for these file patterns and map to a `local.type`:
-
-| If you find... | Use `local.type` | Default include glob |
-|---|---|---|
-| `*.feature` files + `*.cs` project files | `gherkin` (SpecFlow) | `Features/**/*.feature` |
-| `*.feature` files (no .cs) | `gherkin` | `specs/**/*.feature` or `features/**/*.feature` |
-| `*.md` files with `### ` headings in a specs folder | `markdown` | `specs/**/*.md` |
-| `*.cs` + `[TestMethod]` or `[Test]` annotations | `csharp` | `**/Tests/**/*.cs` |
-| `*.java` + `@Test` + JUnit/TestNG imports | `java` | `**/src/test/**/*.java` |
-| `*.py` + `def test_` functions | `python` | `tests/**/*.py` |
-| `*.spec.ts` or `*.spec.js` + `@playwright/test` import | `playwright` | `tests/**/*.spec.ts` |
-| `*.cy.ts` or `*.cy.js` + `cypress/` folder | `cypress` | `cypress/e2e/**/*.cy.ts` |
-| `*.test.ts` or `*.test.js` + jest config / `jest` in package.json | `javascript` | `src/**/*.test.ts` |
-| `*.test.ts` + `detox` in package.json | `detox` | `e2e/**/*.test.ts` |
-| `*.java` or `*.kt` in `androidTest/` | `espresso` | `app/src/androidTest/**/*.java` |
-| `*.swift` + `XCUIApplication` usage | `xcuitest` | `UITests/**/*.swift` |
-| `*_test.dart` + `flutter_test` import | `flutter` | `test/**/*_test.dart` |
-| `*.robot` files | `robot` | `tests/**/*.robot` |
-
-If none of the above match, ask the user which framework they use.
-
----
-
-## Step 2 — Collect required config values
-
-Ask the user (or read from their existing environment) for these four values:
-
-| Value | How to find it | Example |
-|---|---|---|
-| **Azure DevOps org URL** | The base URL to their ADO org | `https://dev.azure.com/contoso` |
-| **Project name** | The ADO project name, visible in the breadcrumb | `MyProject` |
-| **Test Plan ID** | Test Plans → click the plan → number in the URL (`?planId=42`) | `42` |
-| **PAT token** | ADO → User Settings → Personal Access Tokens → New Token, scope: **Test Management Read & Write** + **Work Items Read** | (secret) |
-
-If the user already has `AZURE_DEVOPS_TOKEN` in their environment or `.env`, use that — do not ask again.
-
----
-
-## Step 3 — Generate the config file
-
-Write `ado-sync.json` in the project root with these values:
-
-```json
-{
-  "orgUrl": "<orgUrl>",
-  "project": "<project>",
-  "auth": { "type": "pat", "token": "$AZURE_DEVOPS_TOKEN" },
-  "testPlan": { "id": <planId> },
-  "local": {
-    "type": "<local.type>",
-    "include": ["<include glob>"],
-    "exclude": []
-  },
-  "sync": { "markAutomated": true }
-}
-```
-
-For code-based types (`csharp`, `java`, `python`, `javascript`, `playwright`, `cypress`, `detox`, `espresso`, `xcuitest`, `flutter`), always include `"markAutomated": true` — it links the Test Case to the automation method in Azure DevOps.
-
-Add reasonable excludes based on the framework:
-
-| local.type | Suggested excludes |
-|---|---|
-| `csharp` | `["**/*BaseTest.cs", "**/*Helper.cs", "**/*Fixture.cs"]` |
-| `java` | `["**/*BaseTest.java", "**/*Helper.java", "**/*Base.java"]` |
-| `python` | `["tests/conftest.py", "tests/**/helpers.py", "tests/**/fixtures.py"]` |
-| `playwright` | `["**/*.helper.ts", "**/*.fixtures.ts"]` |
-| `javascript` | `["**/*.helper.ts", "**/*.util.ts"]` |
-| `robot` | `["tests/resources/**"]` |
-
----
-
-## Step 4 — Set the token
-
-If the user has not already exported `AZURE_DEVOPS_TOKEN`, add it to a `.env` file:
-
-```
-AZURE_DEVOPS_TOKEN=<their-token>
-```
-
-Add `.env` to `.gitignore` if not already present.
-
----
-
-## Step 5 — Validate the setup
-
-Run:
-
-```bash
-ado-sync validate
-```
-
-Expected output:
-```
-  ✓ Config is valid
-  ✓ Azure connection established
-  ✓ Project "..." found
-  ✓ Test Plan ... found
-All checks passed.
-```
-
-If any check fails:
-
-| Error | Fix |
-|---|---|
-| `Authentication failed` | Token is wrong or expired — generate a new PAT |
-| `Access denied` | PAT is missing Test Management or Work Items scope |
-| `Project not found` | `project` field has a typo — check the ADO breadcrumb |
-| `Test Plan not found` | Wrong `testPlan.id` — check the URL on the Test Plans page |
-| `Config error` | Missing required field — check the error message and fix `ado-sync.json` |
-
----
-
-## Step 6 — Preview, then push
-
-```bash
-# Show what will be created — no changes made
-ado-sync push --dry-run
-
-# Create Test Cases in Azure DevOps and write IDs back into files
-ado-sync push
-```
-
-After push, each test file will have an ID written back (e.g. `@tc:12345`). Commit these changes.
-
----
-
-## Step 7 — (Optional) Set up CI
-
-For GitHub Actions, add to `.github/workflows/test.yml`:
-
-```yaml
-- name: Push test cases to Azure DevOps
-  run: ado-sync push --config-override sync.disableLocalChanges=true
-  env:
-    AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
-
-- name: Publish test results
-  run: ado-sync publish-test-results --testResult results/junit.xml --testResultFormat junit
-  env:
-    AZURE_DEVOPS_TOKEN: ${{ secrets.AZURE_DEVOPS_TOKEN }}
-```
-
-Use `sync.disableLocalChanges=true` in CI so the pipeline never commits ID writeback files.
-
-Add `AZURE_DEVOPS_TOKEN` to the repository's GitHub secrets (Settings → Secrets → Actions).
-
----
-
-## Step 8 — (Optional) Register the MCP server
-
-If the user is using Claude Code, Cursor, or VS Code with GitHub Copilot, register the MCP server so the AI can manage sync operations directly without CLI invocations.
-
-**Claude Code** — add to `~/.claude/claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "ado-sync": {
-      "command": "ado-sync-mcp",
-      "env": {
-        "AZURE_DEVOPS_TOKEN": "<token>",
-        "ADO_SYNC_CONFIG": "<absolute path to ado-sync.json>"
-      }
-    }
-  }
-}
-```
-
-See [mcp-server.md](mcp-server.md) for VS Code and Cursor instructions.
-
----
-
-## Quick decision tree
-
-```
-User has test files?
-  ├─ .feature → local.type: gherkin (or gherkin for SpecFlow)
-  ├─ .cs      → local.type: csharp
-  ├─ .java    → local.type: java (or espresso if in androidTest/)
-  ├─ .py      → local.type: python
-  ├─ .spec.ts/js → local.type: playwright (if @playwright/test) or javascript
-  ├─ .cy.ts/js   → local.type: cypress
-  ├─ .test.ts/js → local.type: javascript (or detox if detox in package.json)
-  ├─ .swift   → local.type: xcuitest
-  ├─ _test.dart → local.type: flutter
-  ├─ .robot   → local.type: robot
-  └─ .md      → local.type: markdown
-
-Token available?
-  ├─ Yes (env var) → write "$AZURE_DEVOPS_TOKEN" in config
-  └─ No → ask user, write to .env, add .env to .gitignore
-
-Run: ado-sync validate → all green?
-  ├─ Yes → ado-sync push --dry-run → ado-sync push → commit ID writebacks
-  └─ No  → fix the failing check (see Step 5 error table above)
-```

package/docs/capability-roadmap.md

@@ -1,280 +0,0 @@
-# Capability Roadmap
-
-This roadmap turns the recent benchmark review into a product-owned plan for expanding ado-sync without copying another tool's terminology or structure.
-
-The goal is straightforward: make large-scale synchronization more predictable, make result publishing more trustworthy, and give teams a cleaner path from single-suite setups to portfolio-scale usage.
-
----
-
-## Current strengths
-
-ado-sync already delivers a solid base:
-
-- bidirectional push and pull for local specs and Azure DevOps test cases
-- broad parser coverage across Gherkin, source-code, tabular, and result-file formats
-- Azure work item linking, state updates, attachments, and field updates
-- test result publishing with multiple input formats
-- higher-level workflows such as stale detection, coverage, trend analysis, AI-assisted generation, and editor integration
-
-The roadmap below focuses on gaps that limit scale, predictability, or user trust.
-
----
-
-## Phase 1: Fix correctness gaps first
-
-### Why this comes first
-
-Some configuration surfaces are documented and typed, but not fully honored at runtime. That weakens confidence in the tool even when the rest of the workflow is sound.
-
-### Priority work
-
-1. Align `publish-test-results` docs, types, and runtime behavior.
-2. Either implement or remove unsupported settings from public docs and config types.
-3. Add focused regression tests around run creation and configuration lookup.
-
-### Main files
-
-- `src/sync/publish-results.ts`
-- `src/types.ts`
-- `docs/publish-test-results.md`
-- `src/__tests__/regressions.test.ts`
-
-### Concrete targets
-
-- honor `publishTestResults.testConfiguration.name` by resolving configuration names to IDs before run creation
-- support explicit test suite targeting for result publication when configured
-- implement deterministic flaky-outcome policies instead of exposing them as no-op configuration
-- document only behavior that is actually live
-
-### Exit criteria
-
-- every documented `publishTestResults` setting is either implemented end-to-end or removed
-- dry-run and live-run behavior produce matching routing decisions
-- regression coverage exists for name-based configuration selection and flaky handling
-
----
-
-## Phase 2: Introduce scoped synchronization
-
-### Problem to solve
-
-Today the model is centered on a plan, optional suite mapping, and local filters. That works for smaller installations, but it does not give teams a strong way to define which remote inventory a configuration owns.
-
-### Product direction
-
-Add a first-class sync target model that tells ado-sync exactly which remote set belongs to a configuration. This should be original to ado-sync, not a copy of anyone else's schema.
-
-### Proposed design direction
-
-Introduce a new top-level concept such as `syncTarget` or `ownership` with selectable modes:
-
-- `tagged` for test cases carrying a generated ownership tag
-- `suite` for test cases managed through a designated suite root
-- `query` for test cases matched by an Azure DevOps query or rule set
-
-This model should work alongside `configurationKey`, not replace it.
-
-### Main files
-
-- `src/types.ts`
-- `src/config.ts`
-- `src/sync/engine.ts`
-- `src/cli.ts`
-- `docs/configuration.md`
-
-### Exit criteria
-
-- push, pull, stale detection, and status all use the same ownership boundary
-- removing a local scenario does not risk touching unrelated remote items
-- multiple configurations can target the same project without collisions
-
----
-
-## Phase 3: Build a real hierarchy engine
-
-### Problem to solve
-
-Current suite support is useful but narrow. It covers basic mapping and conditional routing, but not richer hierarchy construction, cleanup rules, or multiple parallel views of the same inventory.
-
-### Product direction
-
-Create named hierarchy definitions that can materialize test suites from local structure, tags, or explicit routing rules.
-
-### Proposed capabilities
-
-- folder-based hierarchy generation
-- file-based hierarchy generation
-- tag-driven hierarchy generation
-- explicit level rules for multi-level suite trees
-- cleanup policies for stale nodes and stale memberships
-- optional multiple hierarchy outputs from the same local corpus
-
-### Main files
-
-- `src/azure/test-cases.ts`
-- `src/sync/engine.ts`
-- `src/types.ts`
-- `docs/advanced.md`
-- `docs/configuration.md`
-
-### Exit criteria
-
-- hierarchy definitions are declarative and testable
-- hierarchy sync can add, move, and prune memberships safely
-- teams can maintain more than one suite view without duplicating specs
-
----
-
-## Phase 4: Expand the command surface for scale workflows
-
-### Problem to solve
-
-The current command line is clean, but it is missing a few control points that matter in large repositories and CI pipelines.
-
-### Priority work
-
-1. Add source-file filters for push and pull.
-2. Add operation modes such as create-only, link-only, and update-only where applicable.
-3. Add consistent diagnostic controls across commands.
-4. Allow temporary auth and routing overrides in a controlled way.
-
-### Main files
-
-- `src/cli.ts`
-- `src/config.ts`
-- `src/sync/engine.ts`
-- `docs/cli.md`
-
-### Exit criteria
-
-- operators can target a small slice of a large repo without changing config files
-- CI jobs can run low-risk creation-only or link-only flows
-- troubleshooting output is consistent across push, pull, status, and result publication
-
----
-
-## Phase 5: Modernize configuration ergonomics
-
-### Problem to solve
-
-The configuration model is powerful enough for a single repository, but it becomes awkward when shared across many teams or environments.
-
-### Product direction
-
-Make configuration layering easier, safer, and more portable.
-
-### Priority work
-
-1. Support comment-tolerant JSON configuration parsing.
-2. Add optional parent-config discovery through ancestor folders.
-3. Add personal config overlays for credentials and machine-local overrides.
-4. Add reusable remote profiles so org-level connection settings do not need to be copied into every repository.
-
-### Main files
-
-- `src/config.ts`
-- `src/types.ts`
-- `docs/configuration.md`
-- `src/cli.ts`
-
-### Exit criteria
-
-- teams can share base config safely without checking credentials into the repo
-- repository config stays small even when many projects use the same Azure DevOps org
-- the override and inheritance rules are explicit and easy to debug
-
----
-
-## Phase 6: Deepen automation and result publishing
-
-### Problem to solve
-
-The core publishing flow works, but automation metadata and run routing are still simpler than what enterprise teams usually need.
-
-### Product direction
-
-Expand the publishing model so it can express how tests were executed, where runs should land, and how automated metadata should be maintained.
-
-### Priority work
-
-1. Support automation classification rules instead of a single coarse toggle.
-2. Resolve named test configurations at runtime.
-3. Allow controlled publication to more than one destination suite when desired.
-4. Add stronger matching and fallback rules for automated result association.
-5. Expand attachment and comment policies for passing, flaky, and retried tests.
-
-### Main files
-
-- `src/sync/publish-results.ts`
-- `src/azure/test-runs.ts`
-- `src/azure/test-cases.ts`
-- `src/types.ts`
-- `docs/publish-test-results.md`
-
-### Exit criteria
-
-- automation metadata is predictable across push and publish flows
-- result publication can be routed by configuration rather than ad hoc flags alone
-- retry-heavy pipelines produce consistent final outcomes
-
----
-
-## Phase 7: Add extension points instead of hard-coding every variant
-
-### Problem to solve
-
-ado-sync already supports many ecosystems, but every new integration currently tends to require first-party changes.
-
-### Product direction
-
-Introduce a narrow extension model for parser registration, result ingestion, custom routing, and metadata transforms.
-
-### Candidate extension seams
-
-- local spec discovery
-- parser registration
-- result-file ingestion
-- test-case field transformation
-- run-routing policies
-
-### Main files
-
-- `src/types.ts`
-- `src/config.ts`
-- parser modules under `src/parsers/`
-- `src/sync/engine.ts`
-- `src/sync/publish-results.ts`
-
-### Exit criteria
-
-- new ecosystems can be added without invasive changes to the core sync engine
-- experimental integrations can ship behind stable interfaces
-- core maintenance load stays bounded as format coverage expands
-
----
-
-## Recommended implementation order
-
-1. Phase 1: correctness and documentation trust
-2. Phase 2: scoped synchronization model
-3. Phase 4: command-surface improvements needed to operate the new scope model
-4. Phase 3: hierarchy engine
-5. Phase 6: deeper automation and result-routing behavior
-6. Phase 5: configuration ergonomics and shared profiles
-7. Phase 7: extension model
-
-This order reduces user-facing confusion first, then hardens ownership boundaries before adding more advanced routing and hierarchy features.
-
----
-
-## Near-term backlog candidates
-
-If the goal is to start implementation immediately, the highest-value first batch is:
-
-1. fix `publish-test-results` contract drift
-2. add named test configuration lookup
-3. design `syncTarget` ownership schema in `src/types.ts`
-4. wire ownership filtering into `status`, `push`, `pull`, and `stale`
-5. add `--source-file`, `--create-only`, and `--link-only` style command controls
-
-That batch improves trust, reduces operational risk, and lays the foundation for the larger roadmap.