Laravel Cloud

Technical reference synchronized with Yard’s source. File names and development commands refer to the native app repository.

Native Cloud and Studio now use the same CloudCLI contract and per-project CloudDeploymentSession: discovery, account verification, application/environment choices, review, structured activity, live URL and cancellation agree across both surfaces. Opening Cloud, refreshing metadata, configuring an association and reviewing a target do not push or deploy.

Supported CLI and inspected contract

No Cloud CLI was installed on the validation machine. The implementation inspected the official v0.7.2 source at commit 39cc4d32290e030a6e251fc3bf61ea546992c73c in a disposable clone (/tmp/yard-cloud-source-inspection/v0.7.2). No user token file was read for validation and no CLI, Composer package, account or production resource was installed or changed.

The supported machine contract is explicitly Cloud CLI 0.7.2 with PHP 8.3 or later; other versions fail with a remedy before a deployment. The version and PHP requirement come from the pinned source rather than the previous hardcoded 8.2 message. CLI v0.7.2 source, PHP requirement.

Relevant inspected contracts:

These follow the pinned authentication implementation, deployment, first shipment and structured watcher.

Discovery is shared: Yard's managed bin directory, PATH, then the conventional Composer bin locations. Execution selects an installed Yard PHP version meeting the CLI requirement; it does not change the application's pinned PHP. PHP tool invocations disable automatic context prepend and Xdebug tracing. Yard links to the official installation guide instead of installing project or global Composer dependencies as a side effect.

Interactive sign-in and the guided first shipment use the selected Terminal or iTerm. With Warp selected, these two actions open Terminal because Warp's folder URL does not execute a command; the saved terminal preference stays unchanged. Launch/Automation failures are shown before Yard waits for sign-in confirmation. These interactive actions are never opened by refresh.

Review and association

A refresh reads CLI metadata and local Git identity. It does not treat a saved integration marker or the existence of ~/.config/cloud/config.json as proof of a current login. Missing CLI, unsupported tool/PHP, expired credentials and malformed machine responses block the flow.

The review checks accessible origin, the selected environment's branch and the remote commit. An unpushed local commit or a mismatched branch produces a concrete next action in Changes; Yard never pushes implicitly. A first shipment uses the verified remote default branch. The review shows repository, branch, target and remote SHA, plus the first shipment's name, region, database, scheduler and detected-service defaults. It expires after five minutes. Deploy rechecks source, association and selection immediately before submission; changing any of them invalidates the review. An unreviewed/stale ID cannot submit a deployment from another window.

Saving a target is a separate confirmed action. repo:config chooses the organization/application; the environment is verified against that application before being stored. Unknown .cloud/config.json keys survive edits, failed validation restores the prior bytes, malformed input is kept and paths escaping the repository through symlinks are rejected. A successful first shipment records the returned application/environment IDs and live URL without making an extra deployment. Cloud configuration and deployment in task workspaces hold the existing Studio execution lease; they cannot take ownership from an Agents task.

Multiple organizations

The supported CLI has no global organization selector. repo:config can select an organization for an existing application, while a first shipment with several unconfigured accounts cannot be made unambiguous through the documented noninteractive flags. Yard deliberately does not extract credentials to manufacture that selector.

Both surfaces expose the same guided state. For an existing application, the user explicitly provides/selects the Cloud application and organization, saves the association and refreshes. For a new application with several organizations, a confirmed action opens the official interactive cloud ship command in the user's preferred terminal. The CLI guides organization and resource questions. Yard does not silently select an organization or submit a background shipment in this state. This is a supported guided boundary, not a claim that every Cloud question is implemented as a native/browser form.

Activity and cancellation

Both surfaces observe the same operation. Metadata and CLI work run off the main actor. The engine's owned process runner supplies bounded execution, output observation and process-group cancellation. Activity retains only recognized structured fields and redacts messages; unknown payload fields, credentials and raw CLI dumps are not forwarded to the UI. A final successful deployment status is required before reporting success; an exit code of zero or a build-only success is insufficient. Returned links must be HTTPS without embedded credentials or query/fragment secrets. Safe validation fields appear beneath the message in both the final problem and Activity, including CLI error arrays. Failed commands retain their decoded events even when the final result arrives before UI progress callbacks. Once deployment has been invoked, errors warn that remote resources may exist and direct the user to the Cloud dashboard before retrying. Refreshing account/target metadata keeps the last failed operation's explanation; a new review starts a separate attempt.

Cloud is an explicitly managed operation, independent of Studio automatic stacks. Disabling Studio does not stop a deployment already submitted through Cloud. A new browser deployment checks Studio admission again at actual start; native project controls retain their independent lifecycle.

“Stop local command” cancels the local CLI process group. The UI keeps any deployment ID and states that Cloud may already have accepted work or created resources; it does not claim to cancel remote work. No automatic retry follows a canceled, failed or incomplete deployment. Provider validation questions and known field errors remain visible so the user can refresh/review the target before another submission. The Cloud dashboard remains authoritative for remote cancellation/status.

Verification

CloudDeploymentTests has seven shared-contract tests covering first shipment, existing explicit target, no mutation during opening/review/configuration, inaccessible/unpushed source, expired login, unsupported runtime/version, stale source/association, multi-organization guidance without token export, exact association rollback/unknown keys, chunked NDJSON/UTF-8/redaction, questions and incomplete/failing results without retry.

CloudDeploymentAppTests has three application tests. The first exercises both first shipment and redeploy through the actual Cloud WebKit UI → HTTP routes → the same observable native session, using a real disposable fake CLI process. Native and browser review/target/result agree. The second proves an invalid review cannot deploy and cancels a fake CLI that ignores TERM while retaining its submitted deployment ID and the truthful remote-work caveat. The third verifies matching missing-CLI state across the native model and API. All repositories/homes are temporary; Git-network and Cloud responses are injected. No real remote, model, account or deployment is used.

Initial focused result: 7 YardKit + 3 YardApp tests passed, no skips, /tmp/yard-hd013-cloud-tests.log. The final focused run also passed all seven shared and three app cases after the opaque/offscreen native visual fixture and UI/sendability polish, alongside six settings and three nginx tests: 19 passed, no skips, /tmp/yard-hd013-cloud-final-tests.log. Both final native and browser images were inspected for readable target/review information and uncut controls. The later common project-folder guard is separately covered by the expanded proxy HTTP test; a proxy cannot enter Cloud checking or execution. The final terminal-launch correction was compiled and the ten Cloud cases passed again, with no skips (/tmp/yard-hd013-terminal-final-tests.log). No real terminal sign-in was opened; the actual Automation permission/interactive authentication remains a live boundary. Visual artifacts: /tmp/yard-hd013-native-firstship.png and /tmp/yard-hd013-web-firstship.png.

Remaining live boundary

Real Cloud authentication and production deployment were not run and are not prerequisites for this task's fake-CLI contract verification. Other CLI versions require a fresh compatibility review. The supported CLI deploys an environment's remote branch; it has no flag to pin initiation to the reviewed SHA, so an external push between verification and provider initiation is outside Yard's local lease boundary. Engine approval commits and Git delivery policy are unchanged.