layero 0.10.4 → 0.11.0

package/README.md

@@ -53,7 +53,8 @@ bare `npx layero` call then runs the globally installed copy for years.
 ```bash
 layero login          # device flow: prints a URL + code, sign in once (email code or Yandex ID)
 cd my-site
-layero deploy         # detects the framework, packs, uploads, builds, ships
+layero deploy --dry-run   # how the platform will build this folder; uploads nothing, no login needed
+layero deploy         # packs, uploads, the platform builds and ships
 ```
 
 The first `layero deploy` in a directory creates a project and links it via
@@ -70,9 +71,9 @@ The first `layero deploy` in a directory creates a project and links it via
 
 | Command | Description |
 |---|---|
-| `layero init` | Scaffold `.layero/project.json` and write a Layero block into `AGENTS.md` / `CLAUDE.md` / `.cursorrules` (compact index; full skill in `layero-agents`). |
+| `layero init` | Write a Layero block into `AGENTS.md` / `CLAUDE.md` / `.cursorrules` (compact index; full skill in `layero-agents`) and scaffold `.layero/project.json`. Optional: `deploy` links the folder by itself. It records no guessed settings. |
 | `layero login` / `logout` / `whoami` | Browser device-flow sign-in, sign-out, current account. |
-| `layero deploy` | Pack the current directory, build on the platform, publish. `--claim` — without an account. |
+| `layero deploy` | Pack the current directory, build on the platform, publish. `--dry-run` — show the build plan only. `--claim` — without an account. |
 | `layero projects list` | Projects on your account with addresses. |
 | `layero projects create --repo <provider>:<owner/repo>` | Create a project from a repository of a connected provider, apply the detected settings and start the first build (what the dashboard's "Start deploy" button does); `--no-deploy` leaves it in the wizard. Events: `project_created`, `source_connected`, `webhook_installed` \| `webhook_unavailable`, then `setup_applied` + `deploy_started` \| `setup_pending` \| `setup_failed`. |
 | `layero projects delete <slug> --yes` | Delete a project. Irreversible; needs a token with scope `admin`. |
@@ -93,11 +94,21 @@ Run `layero <cmd> --help` for full options.
 
 ## `layero deploy` flags
 
+- `--dry-run` — print how the platform will build this folder and exit:
+  framework, build command, output folder, where each value comes from
+  (`layero.json`, project settings, `package.json`, a framework default), and
+  a `hint` / `next_action` when the folder is a monorepo, a frontend +
+  backend pair, a custom build script or a server. Uploads nothing, needs no
+  login (with a login it also reads the settings of a linked project).
 - `--type <preset>` — framework override: `vite`, `vitepress`, `next`,
   `astro`, `cra`, `sveltekit`, `nuxt`, `gatsby`, `docusaurus`, `eleventy`
-  (alias `11ty`), `hugo`, `static`; runtime kinds `node_web`, `python_web`,
-  `flask`, `streamlit`, `gradio`, `ssr_next` (aliases `express`, `fastapi`,
-  `django`, …). **Optional** — auto-detected when omitted.
+  (alias `11ty`), `hugo`, `static`, `generic`; runtime kinds `node_web`,
+  `python_web`, `flask`, `streamlit`, `gradio`, `ssr_next` (aliases
+  `express`, `fastapi`, `django`, …). **Optional** — detected by the
+  platform when omitted. `static` serves the files as they are and never runs
+  a build; `generic` runs your own build command (`layero.json`
+  `buildCommand` or the `build` script) and serves the folder with
+  `index.html`.
 - `--prebuilt [dir]` — ship an already-built artifact instead of building
   remotely. Without an argument, picks the first existing of `dist/`,
   `build/`, `public/`, `out/`, `_site/`, `.output/public/`,
@@ -106,13 +117,18 @@ Run `layero <cmd> --help` for full options.
 - `--name <name>` — project name (only on first deploy).
 - `--project <id_or_slug>` — deploy into an existing project, ignoring
   `./.layero/project.json` (use this in CI, not `--name`).
-- `--prod` — target the production environment of a repository-linked
-  project. Redundant for CLI projects: they auto-promote on every deploy.
+- `--prod` — only for a project **with a connected repository**: publish this
+  upload at the live address (without it the upload lands in the project's
+  separate `cli` environment). A project without a repository is always
+  published live.
 - `--branch <name>` — **refused** (`branch_unsupported`, exit 4), see above.
 - `--claim` — deploy without an account: a temporary project for 72 hours
   plus a `claim_url` for a human to take it over. Turns on by itself when
-  there is no token, the run is non-interactive (an agent, not CI) and
-  `--yes` is passed. In CI a missing `LAYERO_TOKEN` stays an error.
+  there is no token, the run is non-interactive (an agent, not CI), `--yes`
+  is passed and the project is new: no `--project`, and the folder is not
+  linked to an account project. An existing project without a token means
+  signing in (`auth_required`). With `--project` it is refused
+  (`claim_with_project`, exit 4). In CI a missing `LAYERO_TOKEN` stays an error.
 - `--org <slug>` — organization for first-time project creation.
 - `--yes` / `-y` — non-interactive mode.
 - `--json` — JSON-lines events on stdout (for agents and CI).
@@ -140,7 +156,15 @@ the page in a browser (in agent mode it prints the link).
 
 ## Framework auto-detection
 
-`layero deploy` (and `layero init`) read your project on disk and pick sane defaults:
+`layero deploy --dry-run` (and `layero init`, and the `detected` event of every
+deploy) read your project on disk with the same rules the platform uses. This
+is **advice, not a decision**: the platform detects again on the uploaded
+files, and nothing the CLI guesses is saved to the project — only what you name
+(`--type`, `--root`, fields you write into `.layero/project.json` or
+`layero.json`). `confident: false` means the folder was not recognised; read
+`hint` and `next_action` (an app in a subfolder → `--root <dir>`, frontend +
+backend → `layero.json` with both halves, a custom build script →
+`"framework": "generic"`).
 
 | Signal | Framework | `build_cmd` | `output_dir` |
 |---|---|---|---|
@@ -156,7 +180,8 @@ the page in a browser (in agent mode it prints the link).
 | `react-scripts` dep | cra | `npm run build` | `build` |
 | `@11ty/eleventy` dep / `.eleventy.js` / `eleventy.config.*` | eleventy | `npm run build` (or `npx @11ty/eleventy`) | `_site` |
 | `hugo.{toml,yaml,json}` or `config.*` with Hugo markers (`baseURL`, `[markup]`, …) | hugo | `hugo --gc --minify` (no install needed) | `public` |
-| any `.html` at root, no `package.json` | static | `true` (no-op) | `.` |
+| `index.html` at the root, no framework | static | none — served as is | `.` |
+| `package.json` with a `build` script, no known framework | generic | `npm run build` | the folder with `index.html` after the build |
 
 ## `layero.json` — pin the settings in the repository
 
@@ -284,7 +309,8 @@ Every command emits events — one JSON object per line on stdout:
 {"event":"sources","org":"…","providers":[…],"connections":[…]}
 {"event":"source_repos","org":"…","connection_id":"…","repos":[…]}
 {"event":"environments","project":"…","environments":[{"branch":"main","url":"https://…","production":true,…}]}
-{"event":"detected","framework":"…","build_cmd":"…","output_dir":"…","confident":true}
+{"event":"detected","framework":"…","build_cmd":"…"|null,"output_dir":"…"|null,"confident":true,"sources":{…},"hint":"…","next_action":"…"}
+{"event":"plan","framework":"…","build_cmd":"…"|null,"output_dir":"…"|null,"sources":{…},"creates_project":true,"replaces_live_site":true,…}   (--dry-run)
 {"event":"packing","files":N,"bytes":N,"sha256":"…"}
 {"event":"uploading"}  {"event":"uploaded","archive_key":"…"}
 {"event":"deploy_started","deploy_id":"…"}
@@ -301,9 +327,11 @@ Every command emits events — one JSON object per line on stdout:
 ```
 
 On `ready`, `url` is the **live public site** — show it as-is and never
-rebuild the hostname from a template. `dashboard_url` is the management page,
-not the site. `preview_url`, `edge_ready` and `edge_eta_seconds` are legacy
-fields; do not wait for them.
+rebuild the hostname from a template. `ready` comes once the address answers
+with the site itself (`edge_ready: true`); `edge_ready: false` with `screen`
+means the platform's own page still answered after the wait — the app did not
+come up, read `layero logs --runtime`. `dashboard_url` is the management page,
+not the site. `preview_url` and `edge_eta_seconds` are legacy fields.
 
 Errors carry a stable `code` (`auth_required`, `auth_expired`, `auth_timeout`,
 `project_unknown`, `project_not_found`, `cli_deploys_disabled`, `invalid_type`,
@@ -338,7 +366,8 @@ the rule files themselves. Maximum archive size is 200 MB.
 - Per-project link: `./.layero/project.json` — `project_id`, `slug`,
   `organization_slug`, `apex_hostname`, `claim` are managed by the CLI;
   `framework_hint`, `build_cmd`, `output_dir`, `analytics_enabled`,
-  `env_vars` are user-editable and override auto-detection.
+  `env_vars` are yours: the CLI never writes guesses there, and what you put
+  there is applied to a new project as your choice.
 
 ## Contributing
 

package/dist/agent.js

@@ -127,10 +127,39 @@ function renderHuman(event) {
             }
             break;
         case "detected":
-            process.stdout.write(event.runtime_kind
-                ? `→ Detected ${event.runtime_kind} runtime app — will deploy as a scale-to-zero container\n`
-                : `→ Detected ${event.framework} (build: ${event.build_cmd}, output: ${event.output_dir})\n`);
+            if (event.runtime_kind) {
+                process.stdout.write(`→ Detected ${event.runtime_kind} runtime app — will deploy as a scale-to-zero container\n`);
+            }
+            else if (event.confident) {
+                process.stdout.write(`→ Detected ${event.framework} (build: ${event.build_cmd ?? "none"}, output: ${event.output_dir ?? "found after the build"})\n`);
+            }
+            else {
+                process.stdout.write(`! Не удалось уверенно определить приложение в этой папке\n`);
+            }
+            if (event.hint)
+                process.stdout.write(`  ${event.hint}\n`);
+            if (event.next_action)
+                process.stdout.write(`  → ${event.next_action}\n`);
+            break;
+        case "plan": {
+            const src = event.sources;
+            process.stdout.write(`План сборки (ничего не выгружено):\n`);
+            process.stdout.write(`  фреймворк: ${event.framework}  (${src.framework})\n`);
+            if (event.runtime_kind)
+                process.stdout.write(`  запуск:    контейнер ${event.runtime_kind}\n`);
+            process.stdout.write(`  сборка:    ${event.build_cmd ?? "не запускается"}  (${src.build_cmd})\n`);
+            process.stdout.write(`  результат: ${event.output_dir ?? "определится после сборки"}  (${src.output_dir})\n`);
+            if (event.root)
+                process.stdout.write(`  папка:     ${event.root}\n`);
+            process.stdout.write(event.replaces_live_site
+                ? `  выкатка заменит живой сайт\n`
+                : `  выкатка ляжет в окружение «cli», живой сайт не изменится\n`);
+            if (event.hint)
+                process.stdout.write(`  ${event.hint}\n`);
+            if (event.next_action)
+                process.stdout.write(`  → ${event.next_action}\n`);
             break;
+        }
         case "prebuilt":
             process.stdout.write(`→ Prebuilt mode: shipping ${event.dir}\n`);
             break;
@@ -186,16 +215,10 @@ function renderHuman(event) {
             break;
         case "ready":
             if (event.edge_ready === false) {
-                // Built & published, but the CDN edge for the apex is still
-                // propagating (first deploy of a new hostname can take a few
-                // minutes on YC CDN). The preview host is reachable immediately.
-                const eta = typeof event.edge_eta_seconds === "number" && event.edge_eta_seconds > 0
-                    ? ` (edge propagating, ~${event.edge_eta_seconds}s)`
-                    : " (edge propagating)";
-                process.stdout.write(`✓ Built. Live at ${event.url}${eta}\n`);
-                if (event.preview_url) {
-                    process.stdout.write(`  Reachable now: ${event.preview_url}\n`);
-                }
+                // Сборка готова, но по адресу всё ещё отвечает экран платформы, а не
+                // приложение: оно не поднялось за время ожидания.
+                process.stdout.write(`✓ Built. ${event.url} still shows the platform screen` +
+                    `${event.screen ? ` (${event.screen})` : ""} — check \`layero logs --runtime\`\n`);
             }
             else {
                 process.stdout.write(`✓ Live at ${event.url}\n`);

package/dist/bin/layero.js

@@ -424,22 +424,33 @@ async function main() {
         .action(tokenSetCmd);
     program
         .command("deploy")
-        .description("Pack the current directory and deploy it. Framework, build command and output directory are auto-detected.")
+        .description("Pack the current directory and deploy it: the platform builds it and publishes it. " +
+        "A project without a connected repository is published live — every deploy replaces the site at ready.url. " +
+        "Framework, build command and output directory are detected by the platform; --dry-run shows the plan first.")
+        .option("--dry-run", "show how the platform will build this folder (framework, build command, output folder, where each came from, " +
+        "hints for monorepos / frontend+backend / custom build scripts) and exit; uploads nothing, needs no login")
         .option("-t, --type <preset>", "type override — static preset (vite | vitepress | next | astro | cra | sveltekit | nuxt | gatsby | docusaurus | storybook | eleventy | hugo | static) " +
-        "or runtime kind for apps the platform RUNS (node_web | python_web | flask | streamlit | gradio | ssr_next; aliases: express, fastapi, django, node, python)")
+        "or runtime kind for apps the platform RUNS (node_web | python_web | flask | streamlit | gradio | ssr_next; aliases: express, fastapi, django, node, python). " +
+        "`static` serves the files as they are and never runs a build; `generic` runs your own build command " +
+        "(layero.json buildCommand or the package.json build script) and serves the folder with index.html")
         .option("--name <name>", "project name (only used on first deploy)")
         .option("--project <id_or_slug>", "deploy into an existing project, ignoring local config")
-        .option("-y, --yes", "non-interactive: accept defaults and skip --prod confirmation")
+        .option("-y, --yes", "non-interactive: accept defaults and skip the --prod confirmation")
         .option("--config", "(legacy alias of the default behaviour — auto-detect + .layero/project.json values)")
         .option("--prebuilt [dir]", "ship an already-built artifact directory (default auto-pick: dist/build/public/out/_site/...)")
-        .option("--root <dir>", "monorepo: subdirectory inside the repo that the builder treats as the app root (saved on the project; future GitHub-push and hook triggers use the same value)")
-        .option("--prod", "deploy to production (replaces apex_hostname's active deploy). Without this flag, deploys go to the project's CLI preview pseudo-branch.")
-        .option("--promote", "pin the project apex to this deploy after a successful build (V071). Works for any branch — e.g. `--promote` without --prod publishes a CLI preview straight to production.")
+        .option("--root <dir>", "monorepo: the app's subfolder (e.g. apps/web) that the builder treats as the app root; the whole folder is still uploaded. " +
+        "Saved on the project, so later deploys and git pushes use it too")
+        .option("--prod", "only for a project WITH a connected repository: publish this upload at the live address. Without it such an upload " +
+        "lands in the project's separate `cli` environment. A project without a repository is always published live")
+        .option("--promote", "after a successful build, point the live address at this deploy (done by the CLI; same result as --prod). " +
+        "Not needed for a project without a repository — it is published live anyway")
         .option("--branch <name>", "REFUSED (branch_unsupported, exit 4): archive uploads always land in the " +
         "reserved `cli` environment, so this flag cannot give you a preview. " +
         "Branch previews come from pushing to a connected repository.")
         .option("--claim", "deploy without an account: a temporary project for 72 hours plus a claim_url for a human to take it over. " +
-        "Turns on by itself when there is no token, the run is non-interactive (agent, not CI) and --yes is passed.")
+        "Turns on by itself when there is no token, the run is non-interactive (agent, not CI), --yes is passed " +
+        "and the project is new (no --project, folder not linked to an account project). " +
+        "Refused together with --project (claim_with_project, exit 4).")
         .option("--org <slug>", "Layero organization slug for first-time project creation. Defaults to personal; required when you're a member of multiple orgs and want a non-personal home.")
         // Осознанное подтверждение выкатки, когда предыдущие сборки подряд падают
         // с ОДНОЙ И ТОЙ ЖЕ ошибкой. Намеренно НЕ покрывается `--yes`: смысл стопа
@@ -447,14 +458,15 @@ async function main() {
         // стоит по умолчанию и снял бы стоп, ничего не остановив.
         .option("--confirm-repeated-failure", "proceed even though recent deploys keep failing with the SAME error (the platform stops repeat deploys until you confirm you know what changed)")
         .addHelpText("after", "\nExamples:\n" +
-        "  $ layero deploy                      # preview deploy (CLI pseudo-branch), auto-detect framework\n" +
-        "  $ layero deploy --prod               # production deploy (interactive confirm)\n" +
-        "  $ layero deploy --prod --yes         # production deploy, no prompt (CI)\n" +
-        "  $ layero deploy --promote            # preview deploy + pin apex (one-shot publish)\n" +
-        "  $ layero deploy --claim              # no account: temporary site + claim link\n" +
-        "  $ layero deploy --type vite          # force a framework preset\n" +
+        "  $ layero deploy --dry-run            # how the platform will build this folder; nothing is uploaded\n" +
+        "  $ layero deploy                      # build and publish (no repository: replaces the live site)\n" +
+        "  $ layero deploy --root apps/web      # monorepo: the app lives in a subfolder\n" +
+        "  $ layero deploy --type generic       # own build script, no known framework: run it, serve the result\n" +
         "  $ layero deploy --type express       # Node backend: platform RUNS it, not serves files\n" +
-        "  $ layero deploy --json               # machine-readable output for agents")
+        "  $ layero deploy --claim              # no account: temporary site + claim link\n" +
+        "  $ layero deploy --prod --yes         # project with a connected repository: publish this upload live (CI)\n" +
+        "  $ layero deploy --json               # machine-readable output for agents\n" +
+        "\nIsolated previews come only from pushing a branch of a connected repository (layero projects create --repo).")
         .action(async (opts) => {
         await deployCmd(opts);
     });