# qa-stlc — end-to-end command behavior

Full lifecycle of every command shipped by `@qa-gentic/stlc-agents`, starting from `npm install`. Includes the `upgrade-framework` command and the framework-drift advisory added in the latest update.

## 1. `npm install -g @qa-gentic/stlc-agents`

Runs `bin/postinstall.js` automatically:

1. Prints the version banner (writes to `/dev/tty` so npm 7+ doesn’t swallow the output).
2. Probes for `python3` / `python` on PATH.
3. Sniffs for PEP 668 by dry-running `pip install` and grepping for `externally-managed-environment`.
4. Ensures `pipx` is on PATH:
   - macOS → `brew install pipx`
   - everywhere else → `pip install --user pipx`
5. Runs `pipx install qa-gentic-stlc-agents` so the five Python MCP servers (`qa-test-case-manager`, `qa-gherkin-generator`, `qa-playwright-generator`, `qa-helix-writer`, `qa-migration`) and `qa-jira-manager` land in their own isolated env.
6. Drops `qa-stlc-apply-cost` on PATH and applies the cost-tracking patch.
7. Leaves `qa-stlc` globally callable via the `bin` entry in `package.json`.

No project-side changes happen here — this is only the global tool install.

## 2. `qa-stlc init [--vscode] [--integration ado|jira|both] [--python <path>]`

Runs in the current project dir. `src/cli/cmd-init.js`:

1. Python probe — same Python 3.10–3.13 hunt as postinstall, dies if nothing compatible is found.
2. Integration resolve — `--integration` flag → `~/.qa-stlc/integration` file → interactive prompt. The choice is saved back to that file.
3. `pip install --upgrade qa-gentic-stlc-agents` into either the active Python, the persistent `~/.qa-stlc/venv`, or a freshly created `~/.qa-stlc/venv`. Quiet by default; tolerates offline (warns and keeps the current version).
4. Copies `ORCHESTRATION_RULES.md` and `migration-guide.md` from the npm package into the project root.
5. Skills — calls `cmd-skills` with `--target claude` (default) or `--target vscode` when `--vscode` is set.
6. MCP config — calls `cmd-mcp-config` with the resolved Python.
7. Framework drift advisory new — compares the project’s on-disk `src/utils/locators/*` and `src/utils/storage-state/*` to the embedded `boilerplate-bundle.js`. If any file has drifted or is missing, prints a `⚠ Self-healing framework files have drifted` notice with the exact `qa-stlc upgrade-framework` commands to inspect and apply. Init never auto-overwrites these files.
8. Prints the integration-specific pipeline summary (ADO and/or Jira sections).

## 3. `qa-stlc skills [--target claude|vscode|cursor|windsurf|both|print]`

`src/cli/cmd-skills.js`:

- Reads integration preference from `~/.qa-stlc/integration` (default `ado`).
- Walks `<package-root>/skills/*/SKILL.md`, filtering: Jira-only skills are excluded when `integration=ado`; ADO-only skills (e.g. `generate-test-cases`) are excluded when `integration=jira`.
- Writes per target:

  Target | Destination
  --- | ---
  `claude` | `.claude/skills/<name>/` (whole skill dir incl. `references/`) + `.claude/AGENT-BEHAVIOR.md`
  `vscode` | `.github/copilot-instructions/<name>/` + `AGENT-BEHAVIOR.md`
  `cursor` | Flat `.cursor/rules/<name>.md`
  `windsurf` | Flat `.windsurf/rules/<name>.md`
  `print` | stdout
  `both` | claude + vscode

- Also copies `.github/agents/*.agent.md` (filtered by integration) and `ORCHESTRATION_RULES.md` to the project root.

## 4. `qa-stlc mcp-config [--vscode] [--print] [--python <bin>] [--playwright-port 8931] [--integration ado|jira|both]`

`src/cli/cmd-mcp-config.js`:

1. Resolves Python and locates each MCP server executable: `./.venv/bin/<name>` → dir of `--python` binary → system PATH → Python’s own bin dir → macOS framework fallback.
2. Builds the server map for the active integration. Each Python server gets the cost env block: `ANTHROPIC_MODEL`, `GITHUB_COPILOT_MODEL`, `STLC_CODING_AGENT_MODEL`, `STLC_COST_TRACKING` — all as `${env:X}` references so Claude Code / VS Code substitute live values.
3. Jira servers additionally get `JIRA_CLIENT_ID`, `JIRA_CLIENT_SECRET`, `JIRA_CLOUD_ID`.
4. Adds a `playwright` entry: `npx @playwright/mcp@latest --isolated`.
5. Writes to `.mcp.json` (Claude Code) or `.vscode/mcp.json` (Copilot). `--print` skips the write and dumps JSON to stdout.

If any server isn’t found locally, the entry is stamped with `"_comment": "NOT FOUND — run: pip install qa-gentic-stlc-agents"` so you see exactly which one needs attention.

## 5. `qa-stlc verify [--playwright-port 8931]`

`src/cli/cmd-verify.js`:

- For each MCP agent name, looks in `.venv` → system PATH and reports ✓/✗.
- Checks the Playwright MCP HTTP endpoint on the given port.
- Filters out servers not relevant for the saved integration.

Pure diagnostic — never writes anything.

## 6. `qa-stlc scaffold --name <name> [--dir <dir>] [--no-install]`

`src/cli/cmd-scaffold.js`:

1. Guards: target dir must be empty (ignoring `.git`).
2. Writes the entire `boilerplate-bundle.js` object to disk — which now contains this repo’s full self-healing locator framework (`LocatorRepository` with the upsert fix, the multi-strategy `LocatorHealer`, `TimingHealer`, `VisualIntentChecker`, `HealingDashboard`, `HealApplicator`, the CI apply pipeline, `dashboard-server`, `review-server`, `ElementContextHelper`).
3. Recursively replaces `{{PROJECT_NAME}}` in every text file.
4. Copies `.env.example` → `.env` if not present.
5. Runs `npm install` (skip with `--no-install`).
6. Prints next-steps for `npx playwright install chromium`, editing `.env`, and `npm test`.

This is the only init-time command that touches `src/utils/locators/*`. `qa-stlc init` deliberately doesn’t.

## 7. `qa-stlc upgrade-framework [--apply] [--dir <dir>] [--include <regex>...]` new

`src/cli/cmd-upgrade-framework.js`:

1. Refuses to run if the target dir has no `src/utils/locators/` (i.e. it wasn’t scaffolded by `qa-stlc`).
2. Scope defaults to `src/utils/locators/*` and `src/utils/storage-state/*`. `--include <regex>` widens it; the original scope is always preserved.
3. For each scoped file in the bundle, classifies on-disk content as match / drift / missing.
4. Default (dry-run) — prints the lists with `~` for drift, `+` for missing, then a one-liner pointing at `--apply`.
5. `--apply` — for each drifted/missing file, writes the bundle version. Existing files are first copied to `<path>.bak.<timestamp>`. Reports total written + backed up + reminds the user to run `npx tsc --noEmit` and `npm test`.

Never touches `src/locators/*.locators.ts`, `src/pages/*`, `src/hooks/*`, or anything outside the default scope unless you explicitly widen with `--include`. Always backs up before overwriting.

## 8. `qa-stlc cost [--all] [--session <id>] [--json] [--set-model <model>] [--model-help]`

`src/cli/cmd-cost.js`: reads `~/.qa-stlc/cost-*.jsonl` (written by `qa-stlc-apply-cost`), prints token usage + estimated cost.

Model detection order: `STLC_CODING_AGENT_MODEL` → `ANTHROPIC_MODEL` → `CLAUDE_MODEL` → `GITHUB_COPILOT_MODEL` → `~/.qa-stlc/agent-model` → `claude-sonnet-4-6`. `--set-model` writes the `agent-model` file.

## 9. Recommended sequences

### Fresh project

    npm install -g @qa-gentic/stlc-agents                        # one-time
    mkdir my-qa-project && cd my-qa-project
    qa-stlc scaffold --name my-qa-project --dir .                # writes the full framework, runs npm install
    qa-stlc init --integration ado                               # writes skills + .mcp.json (no framework changes)
    npx playwright install chromium
    # edit .env: BASE_URL, AI_HEALING_API_KEY, ...
    npm test

### Existing scaffold that pre-dates today’s bundle

    qa-stlc init --integration ado                               # refresh skills, MCP config; you'll get the drift warning
    qa-stlc upgrade-framework                                    # dry-run — see exactly what would change
    qa-stlc upgrade-framework --apply                            # write new framework, back up originals to .bak.<ts>
    npx tsc --noEmit                                             # verify
    npm test

The drift warning in step 1 is what closes the upgrade gap — re-running `init` alone won’t silently leave a buggy `LocatorRepository.ts` in place; it nudges you toward the explicit upgrade command.