Add public API commands

[ramilamparo]

Summary

Adds a new qasphere api command that provides direct CLI access to the full QA Sphere public API. Users can now manage projects, test runs, test cases, results, and other resources programmatically without writing custom API integration code.

What's included

• 16 resource subcommands: projects, runs, test-cases, results, folders, milestones, tags, requirements, shared-steps, shared-preconditions, custom-fields, audit-logs, settings, test-plans, files, users
• Nested subgroups: e.g., qasphere api runs tcases list for run-level test case operations
• JSON argument flexibility: Complex args accept inline JSON or @filename references
• Zod validation with path-based errors: Detailed error messages like [0].tcaseIds: not allowed for "live" runs
• Lazy env loading: QAS_URL/QAS_TOKEN loaded only when the API is called, so CLI validation errors surface first
• Path parameter validation: Regex-based validation prevents injection via crafted identifiers

Other changes

• New API modules: audit-logs, custom-fields, milestones, requirements, results, settings, shared-preconditions, shared-steps, tags, test-plans, users, file — plus expanded runs, tcases, projects, folders
• CLAUDE.md updated with full architecture docs for the API command
• README.md updated with usage documentation
• SKILL.md added for AI coding agent support
• CI workflow updated
• npm audit fix applied to dependencies

Testing

• 55+ new test files under src/tests/api/ covering all resource commands
• Both mocked (MSW) and live test modes supported
• Shared test infrastructure in test-helper.ts with fixtures for project lifecycle
• Global setup for live API authentication
• Missing subcommand help tests

Stats

• 110 files changed, 8,332 insertions, 1,201 deletions
• 14 commits on branch

Open review items

1. Yargs ...rest spread leaks camelCase aliases in ~8 list/count handlers
2. ...restArgs spread in test-cases create/update leaks yargs metadata into request body
3. ...restArgs spread in projects create leaks yargs metadata into schema
4. Shared-preconditions response unwrapping inconsistent with shared-steps
5. ResultStatus | string collapses to string
6. projects create uses .parse() instead of validateWithSchema()
7. test-cases update .check() too restrictive
8. No validation on comma-separated numeric parsing (NaN silently passed)
9. DRY: body-merging logic duplicated in test-cases create/update
10. DRY: duplicated superRefine in runSchema vs createRunBodySchema
11. Non-null assertions on env vars in connectApi()
12. jsonResponse crashes with TypeError on null JSON body

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new api command to the QAS CLI, providing direct access to the QA Sphere public API. This enhancement allows users to manage their QA Sphere projects, test runs, and results programmatically from the command line. The PR also includes significant documentation updates and comprehensive testing to ensure the new functionality is robust and easy to use.

Highlights

• API Command: Introduces a new api command for direct access to the QA Sphere public API, enabling users to manage projects, test runs, and results programmatically.
• Documentation: Extensive documentation updates in README.md and a new SKILL.md file to support AI coding agents, providing detailed command usage and examples.
• Testing: Adds comprehensive tests for the new api command, including both mocked and live modes, ensuring reliability and correctness.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/ci.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive api command to the CLI, providing direct access to the QA Sphere public API. The changes are extensive and well-executed, including new commands for various API resources, detailed documentation in README.md and SKILL.md, and a robust testing suite with both mocked and live tests. The code is well-structured, modular, and follows best practices. My review includes one minor suggestion to enhance error reporting for better user experience when dealing with malformed JSON files.

[gemini-code-assist]

For better error reporting and consistency with the other JSON.parse error handling in this file, it would be beneficial to include the original error message when parsing from a file fails. This will provide more context to the user when debugging malformed JSON files.

try {
			return JSON.parse(content)
		} catch (e) {
			const errorMessage = e instanceof Error ? e.message : String(e)
			throw new Error(
				`Failed to parse JSON from file ${filePath} for ${optionName}: ${errorMessage}`
			)
		}

[claude]

Claude finished @ramilamparo's task in 6m 24s —— View job

---

Reviewing PR #58: Add public API commands

• Gather PR context and diff
• Launch specialized review subagents (code quality, security, performance, test coverage)
• Aggregate findings, deduplicate, and post review
• Clean up outdated bot comments

Reviewed the full diff (~424K chars, 100 files) with 4 specialized subagents (code quality, security, performance, test coverage). Posted a new review with 2 inline comments. Resolved 9 outdated bot threads, minimized 9 outdated bot review summaries, and deleted 2 progress comments.

7 issues fixed since last review:

• ResultStatus type now includes custom1-4 statuses
• test-cases update .check() rewritten (checks empty merged body instead of requiring --body/--title)
• DRY body-merging extracted to mergeBodyWithOverrides helper
• DRY superRefine extracted to shared validateQueryPlans function
• projects create now uses API-layer handleValidationError
• test-cases create/update use explicit field picking (no more ...restArgs body leak)
• listRunTCases correctly unwraps response

Correction on "yargs metadata leak": After deeper analysis, the ...args spread in list/count handlers is NOT a runtime bug — all API functions use validateRequest() which strips unknown keys via Zod before they reach appendSearchParams. Resolved those threads.

2 remaining issues (inline comments posted):

1. milestoneIds/tags arrays missing .int().positive() — allows NaN through (root cause of comma-parsing issue)
2. Shared-preconditions response unwrapping still inconsistent with shared-steps

[claude]

Review Summary (re-review after de6a14d)

Reviewed the full diff (~424K chars, 100 files) with 4 specialized subagents (code quality, security, performance, test coverage).

7 issues fixed since last review — great progress:

• ResultStatus type now includes custom1-4 statuses (was ResultStatus | string → string)
• test-cases update .check() rewritten — no longer requires --body/--title, checks for empty merged body instead
• DRY body-merging logic extracted to mergeBodyWithOverrides helper
• DRY superRefine extracted to shared validateQueryPlans function
• projects create now uses API-layer handleValidationError instead of raw .parse()
• test-cases create/update handlers use mergeBodyWithOverrides with explicit field picking (no more ...restArgs body leak)
• listRunTCases now correctly unwraps response

Correction on prior "yargs metadata leak" findings:
After deeper analysis, the ...args spread in list/count handlers is not a runtime bug. All API functions use validateRequest() → schema.parse(), which strips unknown keys before they reach appendSearchParams or JSON.stringify. The yargs $0, _, and camelCase aliases are silently discarded by Zod. This is a code cleanliness concern (explicit field picking is clearer), not a functional defect.

2 issues still open:

1. Shared-preconditions response unwrapping inconsistent with shared-steps (inline comment)
2. milestoneIds/tags arrays missing .int().positive() — allows NaN, floats, and negatives through validation. This is the root cause of the NaN-in-comma-parsing issue (inline comment)

No new security or performance issues found.