Skip to content

feat: prepare 0.3.1 with Quick Test CLI and agent integration #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
houlianpi merged 1 commit into from
Oct 20, 2026
Merged

feat: prepare 0.3.1 with Quick Test CLI and agent integration #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 18 additions & 3 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,25 @@ All notable changes are documented here. FSQ follows Semantic Versioning after p

## [Unreleased]

## [0.3.1] - 2026-10-20

Release preparation; this entry does not establish a published package, tag, or GitHub release. See the [release notes](docs/releases/v0.3.1.md) for upgrade steps and validation limits.

### Added

- Standalone `fsq quick-test context` and `fsq quick-test run` for Android, Web, Windows, and macOS under existing host/runtime restrictions, without project Workspace setup or an HTTP service.
- Optional Web-only `--url` supplies an exact HTTP(S) starting address separately from the required goal. Existing goal-only execution and the browser Quick Test input remain supported.

### Changed

- The package-owned, host-neutral FSQ Agent Skill now guides a platform-neutral AI testing workflow, with the provider-free Web Strict self-check retained as a fallback.
- The package-owned, host-neutral FSQ Agent Skill guides a platform-neutral AI testing workflow and defaults to standalone Quick Test with actual streamed progress, cancellation of the same process, and evidence-based results. Candidates remain Run-local without Case publication. Explicit Case creation/replay and the provider-free Web Strict troubleshooting fallback remain available; the Codex compatibility integration is unchanged.
- The bilingual README now leads with user value, supports Coding Agent or `fsq ui` entry paths, and keeps detailed onboarding in the user guides.
- Python distribution metadata and current-version guidance are prepared for version 0.3.0. This does not claim publication, merge, or release completion.
- Python distribution metadata is prepared for version 0.3.1. The private npm package keeps its independent version.

### Fixed

- Web goal address parsing recognizes Chinese punctuation, paired wrappers, adjacent address labels, and Markdown boundaries while preserving exact address data and rejecting malformed or ambiguous references.
- Dynamic Web navigation receives the frozen starting address as authoritative task context, including its path, query, fragment, case, and escapes.

## [0.1.6] - 2026-10-13

Expand Down Expand Up @@ -59,7 +73,8 @@ All notable changes are documented here. FSQ follows Semantic Versioning after p

- This is an alpha release. Public APIs and Case authoring details may evolve before 1.0.

[Unreleased]: https://github.com/FSQ-lab/FSQ/compare/v0.1.6...HEAD
[Unreleased]: https://github.com/FSQ-lab/FSQ/compare/v0.3.1...HEAD
[0.3.1]: https://github.com/FSQ-lab/FSQ/compare/v0.3.0...v0.3.1
[0.1.6]: https://github.com/FSQ-lab/FSQ/compare/v0.1.5...v0.1.6
[0.1.5]: https://github.com/FSQ-lab/FSQ/compare/v0.1.0...v0.1.5
[0.1.0]: https://github.com/FSQ-lab/FSQ/releases/tag/v0.1.0
42 changes: 22 additions & 20 deletions SPEC.md
View file
Open in desktop

Large diffs are not rendered by default.

71 changes: 46 additions & 25 deletions docs/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ FSQ installs `fsq` and the compatibility alias `fsq-agent`. Both invoke the same
| `fsq init` | Initialize a Workspace platform, a project-local Coding Agent integration, or both. | No |
| `fsq doctor` | Diagnose configured platforms without mutation. | Yes |
| `fsq providers configure/status` | Configure or inspect the user-level Provider. | No |
| `fsq quick-test context` | Discover platform readiness and device/browser choices without execution. | No project Workspace |
| `fsq quick-test run` | Execute one standalone Explore goal in the dedicated Quick Test Workspace. | No project Workspace |
| `fsq case create` | Execute one AI-driven goal. | Yes |
| `fsq case test` | Execute an existing Case exactly once. | Yes |
| `fsq case test --suggest` | Execute once, then analyze persisted facts. | Yes |
Expand All @@ -25,10 +27,26 @@ FSQ installs `fsq` and the compatibility alias `fsq-agent`. Both invoke the same

Except when creating an unregistered Workspace, Workspace commands use the exact current directory. They do not search ancestors or accept an alternate Workspace flag.

`fsq ui` can start from any directory. Choose **Quick Test** in the browser for exploration using the automatically prepared `~/.fsq/quick-test/` Workspace, or **FSQ Case Manager** for the complete existing workflows. Both use the same **Settings**. Entry selection does not itself start a test, and there is no separate Quick Test CLI command. See [the browser workflow](getting-started.md#open-the-control-plane).
`fsq ui` can start from any directory. Choose **Quick Test** in the browser for exploration using the automatically prepared `~/.fsq/quick-test/` Workspace, or **FSQ Case Manager** for the complete existing workflows. Both use the same **Settings**. Entry selection does not itself start a test. Standalone CLI Quick Test uses the same preparation/execution contracts without starting the HTTP service. See [the browser workflow](getting-started.md#open-the-control-plane).

Human output is for terminals. JSON produces one structured result. JSONL emits documented events and a terminal result where streaming applies. Invalid command requests use exit code 2; consume stable machine fields rather than human wording.

Standalone Quick Test forms:

```bash
fsq quick-test context --platform PLATFORM [--target-id ID]
fsq quick-test run --platform PLATFORM --goal TEXT [--target-id ID] [--url URL]
fsq --output jsonl --non-interactive quick-test run --platform web --target-id chrome --url 'https://example.com/search?q=FSQ#results' --goal "Verify the results contain FSQ"
```

`PLATFORM` is `android`, `web`, `windows`, or `macos`, subject to existing host/runtime prerequisites. Context is read-only: it does not send inference, create a Workspace, or launch an application. A run requires an exact Android device serial or supported Web browser channel in `--target-id`; Windows/macOS reject that run option and resolve application identity from the goal. Choose an available target reported by context.

Web-only `--url` supplies one complete HTTP(S) starting address separately from the required goal. It preserves the exact address, including case, escapes, port, path, query, fragment, and punctuation. Invalid or unsafe addresses fail before inference or Workspace mutation, without correction or search fallback. Keep test actions, expected outcomes, and limits in `--goal`. Without `--url`, existing goal-based address parsing and address-free search remain available. Browser Quick Test retains its single goal field.

Quick Test needs no registered project Workspace and does not inherit the current project's knowledge, private environment, or settings. Runs use the dedicated `~/.fsq/quick-test/` Workspace and shared user-level Provider settings. It is always Explore; recordings remain Run-local, with no save/publication option. Explicit Case creation and strict replay retain their existing commands.

Machine operations are `quick-test.context` and `quick-test.run`. JSON returns one terminal envelope; JSONL streams actual progress followed by one terminal result/error when output remains writable. Context exits `0` when startable and `4` when unavailable. Run exits are `0` success, `1` failed/inconclusive, `2` validation, `3` Workspace/configuration, `4` Provider/runtime unavailable, `5` infrastructure, and `130` cancellation/interruption. Interrupting requests finalization of the same Run; missing terminal facts leave the outcome unknown and do not authorize a retry.

Run export works without browser interaction or a Provider:

```bash
Expand All @@ -46,40 +64,43 @@ Strict check of the `FSQ Web Strict Replay` heading in a package-owned inline
HTML document; a configured browser is its only external prerequisite and the
Skill presents it only as an explicit troubleshooting fallback.

The Skill makes the Coding Agent the dialogue/orchestration owner while FSQ
remains the passive CLI/Application. It requires an exact project directory,
platform/current target, registered Workspace status/root, Goal, acceptance
criteria, allowed/forbidden actions, and permissions. Initialization requires
explicit permission; later commands use the actual returned root and inspect
Doctor readiness for the specific requested command rather than treating an
overall `partial` result as failure.
The Skill defaults to standalone Quick Test. The Coding Agent prepares the
application using authorized project tools, gathers platform/device/browser
facts with `quick-test context`, and resolves only unsettled user choices. It
supplies the full goal, observable acceptance conditions, and action/data
limits; a known Web starting address goes in `--url`. FSQ owns target validation,
UI execution, evidence, and whole-goal verification. The default journey does
not require project Workspace discovery or initialization.

Provider credentials are never a Coding Agent chat input. If Goal creation is
Provider credentials are never a Coding Agent chat input. If Quick Test is
blocked, the preferred handoff is for the user to run `fsq ui` and enter
credentials directly in Settings; private interactive `fsq providers configure`
is the fallback. The Skill does not start or call the UI, receive credentials,
or treat `providers status` as a connection test.

For creation, one exact user-confirmed Goal argument combines the outcome,
acceptance criteria, allowed actions, and forbidden actions. One confirmation
permits one `case create`, with no retry, suggestions, rewriting, parallel
submission, or latest-Run guessing. The Skill preserves FSQ's structured
execution/recording/publication outcomes, selects only the returned
`published_case_path` or returned `candidate_case_path`, and never constructs or
rewrites a Case path. A separately confirmed strict replay uses the exact
unchanged, statically valid canonical Case at most once without `--suggest`;
dynamic success does not prove replay success. Optional Run reads use only an
exact returned/error-detail Run ID with `runs show` or bounded `runs logs`.
The packaged Skill and Codex compatibility agent use terminal
`--output json` for Goal-based creation and accept one result/error envelope.
This integration choice does not remove or change the public CLI's JSONL event
stream for independent programmatic consumers.
The request to verify a goal permits one `quick-test run` submission without a
second FSQ execution confirmation. The Skill uses `--output jsonl` for actual
progress and one terminal result/error, retains the same process for
cancellation, and never automatically resubmits after failure, cancellation,
timeout, or lost output. It leads with FSQ's whole-goal verdict and separately
maps acceptance conditions to returned evidence as supported, unmet, or unknown.
Optional Run reads use only exact returned Workspace/platform/Run identities
with `runs show` or bounded `runs logs`; there is no latest-Run guessing or
Quick Test Case publication.

Explicit Case creation remains a separately requested execution with its
existing publication behavior. Separately confirmed strict replay uses the
exact unchanged, statically valid Case in its registered Workspace at most once
without `--suggest`; Quick Test success does not prove replay success. The Skill
does not author or rewrite Case YAML. The separate Codex compatibility agent
retains terminal `--output json` for Goal-based Case creation.

Review the installed instructions and use the compatible host's discovery/reload
flow. Because installation copies package resources, upgrading the package or
reloading the host alone does not update an existing project copy. After a
package upgrade, rerun `fsq init --agent skill`, review its backup/update result,
then reload discovery or start a new session. `--no-overwrite` deliberately
package upgrade, run `fsq init --agent skill` from the user project directory,
review its backup/update result at `.agents/skills/fsq/`, then reload discovery
or start a new session. `--no-overwrite` deliberately
preserves an older existing copy.

`fsq init --agent codex` retains the compatibility integration: it installs the
Expand Down
91 changes: 91 additions & 0 deletions docs/releases/v0.3.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# FSQ v0.3.1 release preparation

Date: 2026-10-20. Python distribution: `fsq-agent` 0.3.1. FSQ remains alpha.
This record prepares the release; it does not claim a merged PR, existing
`v0.3.1` tag, GitHub release, or PyPI publication.

## Changes

- Standalone `fsq quick-test context` discovers readiness and target choices;
`fsq quick-test run` executes one Explore goal without an HTTP service or
project Workspace setup. Android, Web, Windows, and macOS retain their
existing host/runtime restrictions and external prerequisites. Execution uses
the dedicated Quick Test Workspace and shared user-level Provider settings.
- Web-only `--url` accepts an exact HTTP(S) starting address separately from
`--goal`. The address retains its original spelling, escapes, port, path,
query, fragment, and punctuation. Invalid or unsafe input fails before
inference or mutation. Existing goal-only address identification and
address-free Web search remain supported; browser Quick Test keeps its
existing single goal field.
- Web goal parsing handles adjacent Chinese punctuation, paired Chinese and
fullwidth wrappers, address labels such as `网址:` and `URL:`, and Markdown
link/strong-emphasis boundaries. Complete-reference checks preserve address
data and reject malformed, ambiguous, embedded, or substituted references.
Frozen starting-address context now reaches dynamic Web planning/execution
so the first navigation receives the exact absolute address.
- The host-neutral FSQ Agent Skill defaults to Quick Test. It streams actual
progress, interrupts the same process for cancellation, and reports the
authoritative whole-goal verdict with available evidence. Lost output or a
cancellation request alone does not prove completion; the Skill does not
automatically resubmit. Candidates stay Run-local without Case publication.
Explicit Case creation and strict replay remain available, as does the
provider-free Web troubleshooting Case. The separate Codex compatibility
integration retains its existing workflow.
- The bilingual README presents Coding Agent and `fsq ui` entry paths. The
Python distribution version advances to 0.3.1; the private npm package keeps
its independent 0.1.0 version. No dependency or frontend version change is
part of this release metadata update.

## Upgrade after publication

Once 0.3.1 is published, upgrade the Python environment used by FSQ:

```bash
python -m pip install --upgrade fsq-agent==0.3.1
```

Copied project Skills do not update when the Python package is upgraded. From
the user project directory, explicitly refresh the copy:

```bash
fsq init --agent skill
```

Review the installer's update/backups under `.agents/skills/fsq/`, then start a
new Coding Agent session or reload Skill discovery. `--no-overwrite` preserves
an existing copy. No Workspace reinitialization or Provider reconfiguration
is required solely for this upgrade.

For a known Web starting address, select an available browser reported by
context and pass the address separately:

```bash
fsq quick-test context --platform web
fsq --output jsonl --non-interactive quick-test run --platform web --target-id chrome --url 'https://example.com/search?q=FSQ#results' --goal "Verify the results contain FSQ"
```

Goal-only commands without `--url` remain valid. `fsq ui` remains the browser
entry for Quick Test and FSQ Case Manager. See the [CLI reference](../cli-reference.md)
for command forms, exit codes, target selection, and Case workflows.

## Validation scope and release status

Prior functional QA reported **4,699 Python tests passed and 11 skipped**,
with the real-browser module explicitly excluded at the user's request, plus
**153 frontend tests passed** and a successful frontend typecheck. The prior
functional review passed. The user also reported manual Web and Coding Agent
testing; this is not all-platform live execution evidence. Controlled test
collaborators do not establish live device, browser, model, or host behavior
across all four platforms.

This bounded metadata update is checked with the existing distribution
contract module, including a failing version assertion before the metadata
change and a passing run after it. Final package build/installed-artifact
verification and independent release review remain integration checks. CI for
the final release snapshot is pending; the earlier local results do not claim
a completed release pipeline. Merge, tag creation, GitHub release creation,
and PyPI publication are separate actions outside this preparation.

The prepared [v0.3.0 to v0.3.1 comparison](https://github.com/FSQ-lab/FSQ/compare/v0.3.0...v0.3.1)
uses the canonical repository. The link anticipates release tags and does not
establish that either tag or a publication exists.
Loading
Loading