fix(cli): give veryfront open a way to reach the deployed site

[kojiwakayama]

Symptom

veryfront open resolves only Cloud dashboard URLs. There is no way - flag,
subcommand, or otherwise - to get the URL of the deployed site.

Reproduced against the published CLI (npm veryfront@0.1.1229 installed into a
sandbox prefix, read-only against pre-existing projects):

$ veryfront open --project vf-quickstart-rc --json
{ "data": { "url": "https://veryfront.com/projects/vf-quickstart-rc" } }

$ veryfront open --project vf-quickstart-rc --env production --json
{ "data": { "url": "https://veryfront.com/projects/vf-quickstart-rc/environments/production" } }

$ veryfront open --project vf-quickstart-rc --studio --json
{ "data": { "url": "https://veryfront.com/studio/vf-quickstart-rc" } }

None is https://vf-quickstart-rc.production.veryfront.com, and
veryfront open --help lists no flag that would produce it.

Why the previous fix did not settle this

#3576 (in the 0.1.1229 cut) read the symptom as two problems and fixed one and
a half of them:

1. open exited 1 with "No project found." in a freshly linked directory - it
   never read .veryfront/project.json. Genuinely fixed, and still fixed.
2. The deploy docs claimed open reaches the deployed site. fix(cli): resolve the local project link in veryfront open #3576 corrected
   that claim in veryfront-code/docs/** and test-locked it in
   tests/docs/guide-content.test.ts.

What it did not do was give the CLI the capability the docs had been promising.
It resolved the contradiction by retracting the promise: "record the URL Deploy
printed." That leaves a reader who did not record it with no command at all, and
leaves open --json handing automation a dashboard link.

The doc half also never reached readers. The published site serves
veryfront-docs/docs/code/**, generated from veryfront-code/docs/** by the
auto/update-reference sync workflow - a PR a human merges. It has not landed
since #3576, so veryfront.com still shows the pre-#3576 text. That is a delivery
gap, not a diagnosis error, and re-editing veryfront-code/docs would have
reproduced it exactly. It is fixed at the site in veryfront/veryfront-docs#372.

Change

veryfront open --site opens the deployed environment instead of a dashboard
page:

• --site -> https://<slug>.production.veryfront.com
• --site --env staging -> https://<slug>.staging.veryfront.com
• --site --json -> the same URL in the success envelope

That is the canonical address deploy itself falls back to
(buildEnvironmentUrl in cli/shared/deployment/deploy-project.ts) when an
environment carries no custom domain. open has no API token and cannot read an
environment's configured domains, so --site always builds the canonical form.
An environment with a custom domain is reachable at both, but the origins
differ - the guide says so, and tells automation that needs the custom domain to
record the URL Deploy printed rather than rebuild it from open --site.

Without --site nothing changes: open, open --env <name>, and
open --studio build the same dashboard URLs they did before. --help now
states which is which.

Verification

Original repro command, run against this branch:

$ deno task cli open --project vf-quickstart-rc --site --json
{ "success": true, "command": "open", "data": { "url": "https://vf-quickstart-rc.production.veryfront.com" } }

$ deno task cli open --project vf-quickstart-rc --site --env staging --json
{ "success": true, "command": "open", "data": { "url": "https://vf-quickstart-rc.staging.veryfront.com" } }

$ curl -sSL -o /dev/null -w '%{url_effective} %{http_code}\n' https://vf-quickstart-rc.production.veryfront.com
https://veryfront.com/sign-in?from=https%3A%2F%2Fvf-quickstart-rc.production.veryfront.com%2F 200

The redirect is that project's environment protection, i.e. the host is a live
deployment served by the proxy, not a dashboard route.

The four new buildUrl/parseOpenArgs cases in
cli/commands/open/handler.test.ts were written first and failed on the
unchanged code (site parsed as undefined, dashboard URL returned).

Docs

docs/guides/deploying.md and docs/getting-started/deploy-project.md now name
--site as the way back to the deployed environment, next to the existing note
that plain open is the dashboard shortcut. tests/docs/guide-content.test.ts
locks that in, alongside #3576's existing cases.

Live URLs to check after the docs sync

Once this ships and auto/update-reference runs, these pages must mention
veryfront open --site:

• https://veryfront.com/docs/code/getting-started/deploy-project
• https://veryfront.com/docs/code/guides/deploying

Until then they must not - no released CLI accepts the flag. That is why
veryfront/veryfront-docs#372 corrects the false claim without introducing
--site.

CI note

coverage shard 4/8 failed twice with Promise resolution is still pending but the event loop has already resolved after the shard reported
374 passed (3363 steps) | 0 failed - a post-run leak in the shard that carries
src/transforms/esm/http-cache.test.ts, surfacing as the usual three red checks
(shard, coverage gate, tests (unit)). No assertion failed and no file in
that shard is touched here. Green on re-run without changes.

Summary by CodeRabbit

• New Features

  • Added open --site to open the deployed site directly.
  • Supports selecting an environment, defaulting to production.
  • Added JSON output for retrieving the deployed site URL programmatically.

• Documentation

  • Updated CLI and deployment guides with site-opening workflows, URL behavior, and environment guidance.

• Tests

  • Added coverage for site URLs, environment selection, argument parsing, and related documentation.

[coderabbitai]

Warning

Review limit reached

@kojiwakayama, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 43 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f53dfa25-af63-4e3a-8571-830312711920

📥 Commits

Reviewing files that changed from the base of the PR and between 57940ee and 7f02e33.

📒 Files selected for processing (3)

• cli/commands/open/command.ts
• cli/commands/open/handler.test.ts
• docs/guides/deploying.md

📝 Walkthrough

Walkthrough

The veryfront open command now supports --site to open a deployed site. It builds canonical URLs for production or named environments, supports JSON output, preserves dashboard behavior, and documents the new workflow.

Changes

Deployed site opening

Layer / File(s)	Summary
CLI site URL construction cli/commands/open/command.ts, cli/commands/open/command-help.ts	The command parses --site, uses production by default, builds canonical environment URLs, and documents site and JSON usage.
CLI behavior validation cli/commands/open/handler.test.ts	Tests cover production URLs, named environments, studio precedence, and --site parsing.
Site opening documentation and contracts docs/api-reference/veryfront/cli.md, docs/getting-started/deploy-project.md, docs/guides/deploying.md, tests/docs/guide-content.test.ts	Documentation distinguishes site and dashboard URLs and describes environment, custom-domain, and JSON behavior. Tests require open --site in both deployment guides.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• veryfront/veryfront-code#3576: Modifies veryfront open URL behavior and project resolution.

Suggested reviewers: kwakayama, ariskemper

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a way for veryfront open to reach the deployed site.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/dx-20260811-r2-13

---

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 06d57e1336

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kojiwakayama]

Rebased onto main (was conflicting against 18 new commits, now on top of 6f3242d).

Every file this PR touches had also moved on main, so the resolution is worth stating explicitly.

--env gained a second meaning. #3614 landed after this branch was cut and changed plain --env from /projects/<slug>/environments/<name> (a hard 404) to ?panels=environments. This PR gives --env a different job under --site: naming which deployed environment to open. Neither side could simply win the command-help.ts conflict, so --env now documents both, and --site absorbed the default-environment note that used to sit on --env:

--env <name>   Environment to open with --site; otherwise the Environments panel
--site         Open the deployed site instead of a dashboard page (default env: production)

buildUrl needed no reconciliation — --site returns before the dashboard branches, so #3614's panel logic and its never builds an /environments/ path segment regression guard are untouched and still pass.

Docs. docs/getting-started/deploy-project.md was the same paragraph on both sides; the merged text keeps this PR's --site guidance and #3614's corrected "opens the project's Environments panel" wording rather than restoring "that environment's dashboard page".

tests/docs/guide-content.test.ts kept both new cases — this PR's offers open --site as the way back to the deployed environment URL and #3618's documents a CLI teardown path for cloud projects. Both pass, as does the neighbouring points post-deploy verification at the environment URL, not at open.

docs/api-reference/veryfront/cli.md is generated; regenerated with the CI-pinned Deno 2.7.7 and it produced no diff, so the committed file matches the generator and keeps #3618's veryfront project row.

Behaviour after the rebase, all five paths:

open --site                 -> https://vf-quickstart-rc.production.veryfront.com
open --site --env staging   -> https://vf-quickstart-rc.staging.veryfront.com
open --env production       -> https://veryfront.com/projects/vf-quickstart-rc?panels=environments
open                        -> https://veryfront.com/projects/vf-quickstart-rc
open --studio               -> https://veryfront.com/studio/vf-quickstart-rc

Locally green: fmt --check, lint, typecheck, docs:api-reference:check, lint:cwd-relative-test-reads, plus both touched test files. The diff against main is the same 7 files and the same insertion count as before the rebase; nothing from a sibling branch leaked in.

The P2 review thread about promising the exact Deploy URL was already answered by the second commit (the guide now says --site builds the canonical address and that a custom domain differs in origin); that wording survived the rebase intact, so I resolved the thread.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cli/commands/open/command.ts`:
- Around line 37-44: Update buildSiteUrl to validate both projectSlug and
environment as canonical hostname labels before interpolating them into the URL
authority, reusing existing validators where available; reject invalid values
rather than constructing a non-Veryfront origin. Add regression coverage for
slash, query, and fragment characters in both inputs.

In `@docs/guides/deploying.md`:
- Around line 107-109: Update both site-opening command examples in the
deploying guide to include the --env staging selector, and update the
corresponding verification statement to explicitly verify the staging
environment rather than the default production environment.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e4a1c4ed-94e4-4b5d-bf28-1b0f1091a08b

📥 Commits

Reviewing files that changed from the base of the PR and between 6f3242d and 57940ee.

📒 Files selected for processing (7)

• cli/commands/open/command-help.ts
• cli/commands/open/command.ts
• cli/commands/open/handler.test.ts
• docs/api-reference/veryfront/cli.md
• docs/getting-started/deploy-project.md
• docs/guides/deploying.md
• tests/docs/guide-content.test.ts

[kwakayama]

Findings

• Medium — --site rejects environment names the existing CLI/API contract accepts. cli/commands/open/command.ts:67 requires --env to be a DNS label, so veryfront open --site --env "my env" exits with INVALID_ARGUMENT. However deploy accepts any non-empty environment string (cli/commands/deploy/command.ts:36), the API schema preserves arbitrary environment names (src/platform/adapters/veryfront-api-client/schemas/api.schema.ts:118), and the CLI explicitly tests "my env" as a valid environment reference (cli/commands/pull/command.test.ts:301). This leaves deployments to such environments—especially those with a configured custom domain that Deploy can return—unopenable through the newly documented command, contrary to docs/guides/deploying.md:107 and :179. Resolve the environment/domain through the control plane when possible, or consistently restrict and document the supported environment-name contract; add coverage for a non-DNS environment name.

Rubric: correctness 32/40, tests 15/20, reliability/security 15/15, maintainability 12/15, scope/docs 8/10.

Review-Gate:
Reviewer: Codex
Reviewed-SHA: 7f02e33
Score: 82/100
Actionable-Findings: 1
Verdict: REQUEST_CHANGES