fix(cli): resolve the local project link in veryfront open

[kojiwakayama]

Found during a DX dogfood walk of
getting-started/deploy-project
and guides/deploying, following
the published pages literally. Two findings, one root cause: veryfront open does
not behave the way the deploy journey's final step assumes.

Symptom

Run from the project root seconds after a successful npx veryfront deploy --env production
in that same directory:

$ veryfront open ; echo EXIT=$?
  ✗ No project found.
  Run from a project directory or set --project / VERYFRONT_PROJECT_SLUG
EXIT=1

The directory contains the .veryfront/project.json link that push and deploy
had just written and both had resolved the project from without any flag.
veryfront open --project <slug> and VERYFRONT_PROJECT_SLUG=<slug> veryfront open
both exit 0, isolating the failure to directory-based resolution. --json made it
worse: the failure printed the human banner, so scripted verification could not
parse it.

Separately, no open invocation reaches the deployment:

$ veryfront open --project <slug> --env production --json
{"data":{"url":"https://veryfront.com/projects/<slug>/environments/production"}}

That is the Studio environment page, not the environment URL deploy itself
printed — so "the deployed page and API routes respond" could not be checked via
open at all.

Root cause

cli/commands/open/handler.ts resolved the project with only
getEnvironmentConfig().projectSlug ?? (await readConfigFile(cwd()))?.projectSlug.
That stops two tiers short of the precedence the same docs publish
("… then lower-level tenant or project-ID environment references, then the ignored
local link"): it never consults resolveEnvironmentProjectReference() and never
reads .veryfront/project.json. cli/commands/config/handler.ts already resolves
the full chain; open was the outlier.

The failure branch also called logUsageError unconditionally, ignoring isJsonMode().

buildUrl has only ever produced https://veryfront.com/projects/… dashboard URLs.
That is the intended behavior of the command; the docs describing it as the way to
reach the running deployment were wrong.

Change

• resolveOpenProjectSlug now walks the documented precedence and ends at
  readProjectLinkForControlPlane, the same reader config/push/deploy use —
  including its loud error when the link targets a different control plane, so a
  stale link can never silently open someone else's project.
• reportProjectNotFound emits a PROJECT_NOT_FOUND error envelope under --json
  and keeps the existing banner otherwise.
• Deploy docs point verification at the environment URL Deploy prints and describe
  open as the Cloud dashboard shortcut it is; the post-deploy CLI tip is relabeled
  Dashboard: for the same reason. No behavior claim was invented — the docs now say
  exactly what the command does.

Regression tests

• cli/commands/open/handler.test.ts — Deno BDD, next to the handler it guards.
  Covers the linked-directory case that failed, each precedence tier above the link,
  the control-plane mismatch, and the --json error envelope (captured from the real
  outputJson call, not asserted on a constructed value). Before the fix these fail
  with undefined instead of the linked slug, undefined instead of the tenant
  reference, and SyntaxError: Unexpected end of JSON input because nothing was
  written to stdout.
• tests/docs/guide-content.test.ts — the doc claim is a doc contract, and this file
  is where the repo already pins deploy-doc wording. It fails against the previous
  text on "open opens the deployed project."
• cli/help/tips.test.ts — pins the post-deploy tip label.

Verified after the fix by rerunning the finding's command against the local tree:
veryfront open from the linked directory exits 0 and prints the project URL, and
veryfront open --json with no project anywhere emits a parseable
{"success":false,…,"code":"PROJECT_NOT_FOUND"} envelope with exit 1.

deno task docs:validate passes; the full CLI unit suite and the pre-push gate are green.

Summary by CodeRabbit

• Bug Fixes

  • Updated open to consistently resolve the intended project across command-line, configuration, and local project references.
  • Added clearer project-not-found errors, including JSON-formatted output.
  • Clarified that open opens the Cloud dashboard rather than the deployed site.

• Documentation

  • Updated deployment guidance to use the printed environment URL for verification.
  • Documented dashboard links, JSON output, and production-environment options.
  • Relabeled post-deployment guidance from “Open” to “Dashboard.”

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 34 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: 6a434980-ebec-4f52-ba04-0e27b3668263

📥 Commits

Reviewing files that changed from the base of the PR and between d995056 and 36e09f0.

📒 Files selected for processing (4)

• cli/commands/open/handler.test.ts
• cli/commands/open/handler.ts
• docs/getting-started/deploy-project.md
• docs/guides/deploying.md

📝 Walkthrough

Walkthrough

The open command now resolves project slugs from shared project references, handles missing projects with structured output, and identifies dashboard URLs separately from deployed environment URLs. Help text, post-deploy tips, documentation, and contract tests reflect this distinction.

Changes

Open dashboard flow

Layer / File(s)	Summary
Project resolution and error handling cli/commands/open/handler.ts, cli/commands/open/handler.test.ts	open centralizes project-slug resolution across explicit arguments, configuration, environment variables, control-plane links, and local project links. Missing projects use structured JSON or human-readable errors. Tests cover precedence, invalid references, isolation, and JSON output.
Dashboard command messaging cli/commands/open/command-help.ts, cli/help/tips.ts, cli/help/tips.test.ts	Help text and post-deploy tips identify veryfront open as opening the dashboard.
Deployment verification documentation docs/getting-started/deploy-project.md, docs/guides/deploying.md, tests/docs/guide-content.test.ts	Deployment guides use the printed environment URL for site verification and describe open as opening the Cloud dashboard. Documentation tests enforce this distinction.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant OpenHandler
  participant ResolveOpenProjectSlug
  participant ProjectReferences
  participant ControlPlane
  OpenHandler->>ResolveOpenProjectSlug: resolve project slug
  ResolveOpenProjectSlug->>ProjectReferences: inspect project references
  ProjectReferences->>ControlPlane: validate control-plane link
  ControlPlane-->>ResolveOpenProjectSlug: return validated reference
  ResolveOpenProjectSlug-->>OpenHandler: return slug or missing result

Loading

Possibly related PRs

• veryfront/veryfront-code#3507: Related CLI project-slug resolution and project-specific command behavior.

Suggested reviewers: kwakayama, ariskemper

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main CLI fix: resolving the local project link in veryfront open.
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 💡 1

📝 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-b2-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: d995056b55

ℹ️ 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".

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@docs/getting-started/deploy-project.md`:
- Around line 85-90: Add a route-specific verification command alongside the
existing root URL curl, using a documented API route and its required HTTP
method and headers; alternatively revise the surrounding text to claim only page
verification. Update the deployment verification instructions without changing
unrelated steps.

🪄 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: a7183e12-0d26-45b1-b3b3-00b07b858cf3

📥 Commits

Reviewing files that changed from the base of the PR and between f231bc4 and d995056.

📒 Files selected for processing (8)

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