qa-stlc — end-to-end command behavior

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.