From d084d41b7db3ff4634d7f6b4a63300cb6bbdd938 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=92=D0=B0=D0=BB=D0=B5=D0=BD=D1=82=D0=B8=D0=BD?= Date: Mon, 27 Jul 2026 01:35:55 +0300 Subject: [PATCH 1/4] feat: add Layero deployment rule --- README.md | 1 + rules/layero-deployment.mdc | 91 +++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 rules/layero-deployment.mdc diff --git a/README.md b/README.md index 8204dac5..b71573d9 100644 --- a/README.md +++ b/README.md @@ -233,6 +233,7 @@ By adding selected `.mdc` files to `.cursor/rules/`, you can use these rules dir ### Hosting and Deployments - [Cloudflare Email to Telegram](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/cloudflare-email-telegram-cursorrules-prompt-file.mdc) - Setting up email-to-Telegram forwarding via Cloudflare Email Routing and Workers using the mail2tg CLI. +- [Layero](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/layero-deployment.mdc) - Deploying static sites and SPAs from the agent terminal, driving the CLI through its JSON-lines event stream. - [Netlify](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/netlify-official-cursorrules-prompt-file.mdc) - Official deployment platform integration. - [Vercel](https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/vercel-deployment-cursorrules-prompt-file.mdc) - Deployment with serverless functions, Edge Runtime, middleware, caching, CI/CD, and production-ready configuration. diff --git a/rules/layero-deployment.mdc b/rules/layero-deployment.mdc new file mode 100644 index 00000000..10c190b0 --- /dev/null +++ b/rules/layero-deployment.mdc @@ -0,0 +1,91 @@ +--- +description: "Deploying static sites and SPAs to Layero from the agent terminal, driving the CLI through its JSON-lines event stream" +globs: package.json, vite.config.*, next.config.*, astro.config.*, nuxt.config.*, svelte.config.*, **/.layero/project.json +alwaysApply: false +--- +# Layero Deployment + +Layero is a deployment platform for static sites and SPAs with build servers +and CDN located inside Russia. It ships a local directory — a git repository +is not required. + +Trigger this procedure when the user asks to deploy, publish or ship the +project and mentions Layero. + +## Deploy + +Run from the project root: + +```bash +npx layero@latest deploy --json +``` + +`--json` switches the CLI to JSON-lines output — one JSON object per line on +stdout. Parse the stream rather than scraping human-readable text. + +If the directory has no `.layero/project.json`, run `npx layero init` first. +It detects the framework, writes the config, and appends a rules block to +`AGENTS.md` so later sessions follow the same procedure. + +## What not to do + +- Do not run `git init` or push to GitHub first. Git is optional here; the + unit of deployment is a directory. +- Do not run `npm install -g layero`. Global installs fail in sandboxed agent + terminals. Use `npx layero@latest`, or `npm install -D layero`. +- Do not open the dashboard to "finish setup". The CLI does everything + inline; there has been no browser setup wizard since v0.5.0. +- Do not pass `--provider` to `layero login`. The flag was removed in v0.5.x; + the provider is chosen in the browser. +- Do not pass `--prod` unless the user explicitly asked for production. + Without it a deploy is an isolated preview and cannot affect the live site. + +## Events to handle + +``` +auth_required, authorized, project_created, project_linked, detected, +packing, uploading, uploaded, setup_applied, deploy_started, stage, +build_log, ready, error +``` + +- `auth_required` carries `url` and `user_code`. Render the URL as a + clickable link. The user signs in once; the CLI's poll loop picks up the + token within about two seconds and caches it in `~/.layero/config.json`. + There is no localhost callback, so the browser may be on a different + machine than the terminal — this works from SSH, Docker and sandboxes. +- `detected` is informational: framework, build command, output directory. + Do not override detection unless it is demonstrably wrong. +- `build_log` is raw build output. Forward it only when it contains errors. +- `ready` carries `url` — the live address. Show it as-is. **Never construct + the hostname from a template**: addresses live in a dedicated zone and + organizations migrate between schemes, so a guessed host will be wrong. + `preview_url` and `edge_ready` are legacy fields; do not gate on them. +- `error` carries a stable `code` and a `next_action` hint. Follow + `next_action`. Common codes: `not_logged_in`, `auth_expired`, + `auth_timeout`, `invalid_type`, `project_not_found`, `project_unlinked`, + `cli_deploys_disabled`, `deploy_failed`, `deploy_timed_out`. + +## Redeploying + +Run the same command again. The first deploy creates the project, later ones +reuse it. No commit is needed between runs. + +## CI + +Browser sign-in cannot work on a runner. Pipelines use a long-lived token +created in the dashboard and passed through the environment: + +```bash +LAYERO_TOKEN=... npx layero@latest deploy --prod --yes +``` + +`LAYERO_TOKEN` takes priority over a cached local login, which matters on a +developer machine that is signed in to a different account. `--yes` skips the +confirmation prompt that would otherwise wait forever with no one to answer +it. + +## Reference + +- CLI package: +- JSON event schema: +- Agent guide: From 359f9adfd3f74d098904f9fdbf0094060b964335 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=92=D0=B0=D0=BB=D0=B5=D0=BD=D1=82=D0=B8=D0=BD?= Date: Mon, 27 Jul 2026 23:23:11 +0300 Subject: [PATCH 2/4] fix: correct the preview/production guidance the reviewer flagged MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CodeRabbit was right on both counts, and both were verified against the live platform rather than the docs: 1. Omitting `--prod` is NOT an isolated preview. For a project created from the CLI, direct uploads auto-promote — every deploy replaces what visitors see. `--prod` only matters for projects with a connected git repository. 2. `--branch` is not a usable flag. It is accepted and silently ignored for direct uploads: the backend files every archive deploy under the reserved `cli` environment. Reproduced on a live project — passing `--branch=probe` created no `probe` environment and changed the live site. Isolated previews come from pushing to a branch of a connected repository, and the rule now says so instead of pointing agents at an unsupported flag. Two more corrections while here: - the CI example used `--prod`; it now uses `--project`, which is what a repeatable pipeline needs. `--name` only labels a project at creation, so a pipeline without a link creates a new project on every run. - reference links pointed at the Russian docs from an English rule; switched to the `/en/` pages (both verified 200). --- rules/layero-deployment.mdc | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/rules/layero-deployment.mdc b/rules/layero-deployment.mdc index 10c190b0..daf0690a 100644 --- a/rules/layero-deployment.mdc +++ b/rules/layero-deployment.mdc @@ -37,8 +37,16 @@ It detects the framework, writes the config, and appends a rules block to inline; there has been no browser setup wizard since v0.5.0. - Do not pass `--provider` to `layero login`. The flag was removed in v0.5.x; the provider is chosen in the browser. -- Do not pass `--prod` unless the user explicitly asked for production. - Without it a deploy is an isolated preview and cannot affect the live site. +- Do not assume a plain `layero deploy` is a safe preview. For a project + created from the CLI it is **not**: direct uploads auto-promote, so every + deploy replaces what visitors see at `.layero.app`. `--prod` + matters only for projects with a connected git repository, where it targets + the production environment. +- Do not offer `--branch` as a way to publish somewhere isolated. The flag is + accepted and silently ignored for direct uploads — the backend files every + archive deploy under the reserved `cli` environment. Isolated previews come + from pushing to a branch of a connected repository, nothing else. If the + user wants a version "just to look at", say that it needs a repository. ## Events to handle @@ -76,7 +84,7 @@ Browser sign-in cannot work on a runner. Pipelines use a long-lived token created in the dashboard and passed through the environment: ```bash -LAYERO_TOKEN=... npx layero@latest deploy --prod --yes +LAYERO_TOKEN=... npx layero@latest deploy --project my-site --yes ``` `LAYERO_TOKEN` takes priority over a cached local login, which matters on a @@ -84,8 +92,12 @@ developer machine that is signed in to a different account. `--yes` skips the confirmation prompt that would otherwise wait forever with no one to answer it. +Pass `--project` in a pipeline, not `--name`. `--name` only labels a project +at creation, so a repeated pipeline run without a link creates a **new** +project every time instead of updating one. + ## Reference - CLI package: -- JSON event schema: -- Agent guide: +- JSON event schema: +- Agent guide: From 334b7ff782860185e9ef8b627ac4b7f784c09610 Mon Sep 17 00:00:00 2001 From: borisowvalia Date: Tue, 28 Jul 2026 00:11:52 +0300 Subject: [PATCH 3/4] Drop the hard-coded hostname, add --json to the CI example The rule told readers never to construct a deployment hostname and then printed a host template two paragraphs earlier. Replaced it with the ready.url the previous deploy emitted, which is what the rule already tells agents to read. The CI example omitted --json, so a pipeline had nothing parseable to branch on. --- rules/layero-deployment.mdc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/rules/layero-deployment.mdc b/rules/layero-deployment.mdc index daf0690a..76300aea 100644 --- a/rules/layero-deployment.mdc +++ b/rules/layero-deployment.mdc @@ -39,9 +39,9 @@ It detects the framework, writes the config, and appends a rules block to the provider is chosen in the browser. - Do not assume a plain `layero deploy` is a safe preview. For a project created from the CLI it is **not**: direct uploads auto-promote, so every - deploy replaces what visitors see at `.layero.app`. `--prod` - matters only for projects with a connected git repository, where it targets - the production environment. + deploy replaces what visitors see at the project's public address — the same + `ready.url` the previous deploy printed. `--prod` matters only for projects + with a connected git repository, where it targets the production environment. - Do not offer `--branch` as a way to publish somewhere isolated. The flag is accepted and silently ignored for direct uploads — the backend files every archive deploy under the reserved `cli` environment. Isolated previews come @@ -84,13 +84,14 @@ Browser sign-in cannot work on a runner. Pipelines use a long-lived token created in the dashboard and passed through the environment: ```bash -LAYERO_TOKEN=... npx layero@latest deploy --project my-site --yes +LAYERO_TOKEN=... npx layero@latest deploy --project my-site --json --yes ``` `LAYERO_TOKEN` takes priority over a cached local login, which matters on a developer machine that is signed in to a different account. `--yes` skips the confirmation prompt that would otherwise wait forever with no one to answer -it. +it. Keep `--json` here too: a runner has no one reading the terminal, and the +`ready` / `error` events are what a pipeline step can actually branch on. Pass `--project` in a pipeline, not `--name`. `--name` only labels a project at creation, so a repeated pipeline run without a link creates a **new** From da3286abaed0d345ec45f0ec0597e5420e9368a6 Mon Sep 17 00:00:00 2001 From: borisowvalia Date: Tue, 28 Jul 2026 01:53:13 +0300 Subject: [PATCH 4/4] Correct the error codes: seven of them the CLI never emits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I listed not_logged_in, project_unlinked and deploy_timed_out from our own docs. Checking against the CLI sources today, those codes appear nowhere in src — they were emitted by an earlier version and the docs never followed. deploy_error and deploy_timed_out cannot occur at all: the code is assembled as deploy_ and a deploy only has ready, building, failed and cancelled. Replaced with the set the CLI actually emits, and stated the deploy_ rule so the list cannot drift again. --- rules/layero-deployment.mdc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/rules/layero-deployment.mdc b/rules/layero-deployment.mdc index 76300aea..d17336d5 100644 --- a/rules/layero-deployment.mdc +++ b/rules/layero-deployment.mdc @@ -69,9 +69,13 @@ build_log, ready, error organizations migrate between schemes, so a guessed host will be wrong. `preview_url` and `edge_ready` are legacy fields; do not gate on them. - `error` carries a stable `code` and a `next_action` hint. Follow - `next_action`. Common codes: `not_logged_in`, `auth_expired`, - `auth_timeout`, `invalid_type`, `project_not_found`, `project_unlinked`, - `cli_deploys_disabled`, `deploy_failed`, `deploy_timed_out`. + `next_action`. The codes the CLI actually emits are `auth_required`, + `auth_expired`, `auth_timeout`, `project_unknown`, `project_not_found`, + `cli_deploys_disabled`, `invalid_type`, `prebuilt_no_dir`, + `prebuilt_no_index`, `deploy_not_started`, `deploy_failed` and `internal`. + The failure code is assembled as `deploy_` and the only failing + statuses are `failed` and `cancelled`, so `deploy_error` and + `deploy_timed_out` never occur. ## Redeploying