layero 0.10.5 → 0.11.1

package/dist/detect.js

@@ -17,7 +17,27 @@ async function readText(p) {
         return null;
     }
 }
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 const HTML_SKIP_DIRS = new Set(["node_modules", ".git", ".cache", "dist", "build", "out", "public"]);
+/**
+ * Есть ли в дереве html, который можно отдать КАК ЕСТЬ.
+ *
+ * 🚨 Папка со своим `package.json` — это чужое приложение, и её `index.html`
+ * — исходник, а не статика. Сборщик различает это с 23.08.2026
+ * (`detect_core._dir_has_html`), а CLI — нет: у монорепо `apps/web/index.html`
+ * поднимал флаг, и корень с одним README уверенно становился «static,
+ * confident: true». Эту догадку CLI затем записывал в проект, и сборщик
+ * выкладывал исходники Vite-приложения без сборки (симуляция 18.09.2026,
+ * T-20260918-7).
+ */
 async function dirHasHtml(base, depth = 0) {
     if (depth > 6)
         return false;
@@ -28,6 +48,8 @@ async function dirHasHtml(base, depth = 0) {
     catch {
         return false;
     }
+    if (depth > 0 && entries.some((e) => e.isFile() && e.name === "package.json"))
+        return false;
     for (const e of entries) {
         if (e.isFile() && (e.name.endsWith(".html") || e.name.endsWith(".htm")))
             return true;
@@ -40,6 +62,14 @@ async function dirHasHtml(base, depth = 0) {
     }
     return false;
 }
+async function rootHasIndexHtml(cwd) {
+    try {
+        return (await fs.readdir(cwd)).some((n) => n.toLowerCase() === "index.html");
+    }
+    catch {
+        return false;
+    }
+}
 /** Build a detect_core Snapshot from the local filesystem (the CLI's disk
  * fidelity — the analogue of detect_core.py's snapshot_from_dir). */
 async function snapshotFromDir(cwd) {
@@ -57,13 +87,8 @@ async function snapshotFromDir(cwd) {
         ".vitepress/config.ts", ".vitepress/config.js", ".vitepress/config.mts", ".vitepress/config.mjs",
         "docs/.vitepress/config.ts", "docs/.vitepress/config.js", "docs/.vitepress/config.mts", "docs/.vitepress/config.mjs",
     ]) {
-        try {
-            await fs.access(path.join(cwd, nested));
+        if (await exists(path.join(cwd, nested)))
             files.add(nested);
-        }
-        catch {
-            /* absent */
-        }
     }
     const packageJson = (await readJson(path.join(cwd, "package.json")));
     const requirementsTxt = await readText(path.join(cwd, "requirements.txt"));
@@ -132,47 +157,523 @@ function ssrWarning(snap, framework) {
     }
     return undefined;
 }
+// ── Форма папки ─────────────────────────────────────────────────────────────
+//
+// Детект отвечает, ЧТО лежит в папке. Он не отвечает, почему в ней ничего не
+// узнано: приложение в подпапке, две половины рядом, свой скрипт сборки или
+// сервер без известного фреймворка. До 18.09.2026 на все эти формы CLI
+// отвечал одним `static, confident: true` — и агенту оставалось верить.
+// Ниже — подсказки для этих форм. Вердикта они не меняют: решает сборщик.
+// Зеркало `_SCAN_SKIP` / `_APP_MANIFESTS` сборщика (`frameworks/base.py`,
+// `find_app_subdirs`): кандидатов CLI называет по тому же правилу, по
+// которому сборщик сам выбирает единственную папку приложения.
+const SCAN_SKIP = new Set([
+    "node_modules", ".git", ".github", ".cache", ".turbo", ".vercel",
+    "coverage", "__pycache__", ".angular", ".next", ".nuxt", ".svelte-kit",
+    "vendor", ".gradle",
+]);
+const APP_MANIFESTS = ["package.json", "requirements.txt", "pyproject.toml", "layero.json", "go.mod", "Gemfile"];
+const WORKSPACE_FILES = ["pnpm-workspace.yaml", "lerna.json", "rush.json", "turbo.json", "nx.json"];
+const MAX_CANDIDATES = 12;
+async function hasAppManifest(dir) {
+    for (const m of APP_MANIFESTS)
+        if (await exists(path.join(dir, m)))
+            return true;
+    return false;
+}
+/** Папки с манифестом приложения на глубине 1–2, мельчайшие первыми. */
+async function findAppSubdirs(base, maxDepth = 2) {
+    const found = [];
+    async function walk(rel, depth) {
+        let entries;
+        try {
+            entries = await fs.readdir(path.join(base, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || SCAN_SKIP.has(e.name) || e.name.startsWith("."))
+                continue;
+            const child = rel ? `${rel}/${e.name}` : e.name;
+            if (await hasAppManifest(path.join(base, child))) {
+                found.push(child);
+                continue; // вложенные манифесты приложения — не отдельные приложения
+            }
+            if (depth + 1 < maxDepth)
+                await walk(child, depth + 1);
+        }
+    }
+    await walk("", 0);
+    found.sort((a, b) => a.split("/").length - b.split("/").length || a.localeCompare(b));
+    return found;
+}
+const LOCAL_DEP_RE = /^(workspace:|file:|link:|portal:)/;
+function scriptOf(pkg, name) {
+    const v = pkg?.scripts?.[name];
+    return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+function isWorkspaceContainer(snap) {
+    const pkg = snap.packageJson;
+    return Boolean(pkg && pkg.workspaces) || WORKSPACE_FILES.some((f) => snap.files.has(f));
+}
+async function describeCandidate(base, dir, siblingNames) {
+    const abs = path.join(base, dir);
+    const snap = await snapshotFromDir(abs);
+    const plan = dc.detect(snap);
+    const pkg = snap.packageJson;
+    const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    const workspaceDeps = Object.entries(deps).some(([name, v]) => (typeof v === "string" && LOCAL_DEP_RE.test(v)) || siblingNames.has(name));
+    let role = "unknown";
+    if (plan.runtimeKind !== null && plan.projectType !== "ssr_next")
+        role = "server";
+    else if (plan.runtimeKind !== null)
+        role = "app";
+    else if (plan.framework !== "static" && plan.framework !== "generic")
+        role = "app";
+    else if (await rootHasIndexHtml(abs))
+        role = "app";
+    else if (isWorkspaceContainer(snap) && !scriptOf(pkg, "build"))
+        role = "workspace";
+    else if (pkg && (pkg.exports || pkg.main || pkg.module || pkg.types) && !scriptOf(pkg, "start"))
+        role = "library";
+    else if (scriptOf(pkg, "build") || scriptOf(pkg, "start"))
+        role = "app";
+    return {
+        dir,
+        role,
+        framework: plan.framework,
+        outputDir: plan.runtimeKind === null ? plan.outputDir : null,
+        packageName: typeof pkg?.name === "string" ? pkg.name : undefined,
+        workspaceDeps,
+    };
+}
+async function describeCandidates(base, dirs) {
+    const names = new Set();
+    for (const d of dirs) {
+        const pkg = (await readJson(path.join(base, d, "package.json")));
+        if (pkg && typeof pkg.name === "string")
+            names.add(pkg.name);
+    }
+    const out = [];
+    for (const d of dirs.slice(0, MAX_CANDIDATES)) {
+        const own = (await readJson(path.join(base, d, "package.json")));
+        const siblings = new Set([...names].filter((n) => n !== own?.name));
+        out.push(await describeCandidate(base, d, siblings));
+    }
+    return out;
+}
+const FRONT_NAMES = ["frontend", "client", "web", "app", "site", "ui"];
+const BACK_NAMES = ["backend", "server", "api"];
+function pickByName(list, names) {
+    return list.find((c) => names.includes(path.basename(c.dir).toLowerCase())) ?? list[0];
+}
+function label(c) {
+    return `${c.dir} (${c.framework})`;
+}
+function fullstackRecipe(front, back) {
+    const fe = { root: front.dir };
+    if (front.outputDir && front.outputDir !== "." && front.outputDir !== "dist")
+        fe.output = front.outputDir;
+    const be = { root: back.dir };
+    if (back.framework && back.framework !== "generic")
+        be.framework = back.framework;
+    return JSON.stringify({ frontend: fe, backend: be, apiPrefix: "/api" });
+}
+function workspaceBuildCmd(snap, c) {
+    const pnpm = snap.files.has("pnpm-workspace.yaml") || snap.files.has("pnpm-lock.yaml");
+    if (pnpm && c.packageName)
+        return `pnpm --filter ${c.packageName}... build`;
+    return "npm run build --workspaces --if-present";
+}
+/**
+ * Что сказать про папку, которую детект не узнал.
+ *
+ * Порядок — от самой частой формы в отказах прода (монорепо и не та папка —
+ * 14,8 % отказов, серии до 61 подряд) к редким.
+ */
+async function shapeOf(cwd, snap, plan) {
+    const pkg = snap.packageJson;
+    const dirs = await findAppSubdirs(cwd);
+    const described = await describeCandidates(cwd, dirs);
+    const apps = described.filter((c) => c.role === "app" || c.role === "server");
+    const candidates = apps.map((c) => c.dir);
+    const servers = apps.filter((c) => c.role === "server");
+    const fronts = apps.filter((c) => c.role === "app");
+    if (servers.length >= 1 && fronts.length >= 1) {
+        const front = pickByName(fronts, FRONT_NAMES);
+        const back = pickByName(servers, BACK_NAMES);
+        return {
+            hint: `${label(front)} looks like the site and ${label(back)} like its server. ` +
+                "Without layero.json the platform builds only one app folder, so the other half would be missing. " +
+                "Describe both halves in layero.json at the root of this folder.",
+            next_action: `create layero.json here: ${fullstackRecipe(front, back)} — then deploy from this folder`,
+            candidates,
+        };
+    }
+    if (apps.length === 1) {
+        const c = apps[0];
+        const workspace = isWorkspaceContainer(snap);
+        if (c.workspaceDeps) {
+            const out = `${c.dir}/${c.outputDir && c.outputDir !== "." ? c.outputDir : "dist"}`;
+            const recipe = { framework: "generic", buildCommand: workspaceBuildCmd(snap, c), outputDirectory: out };
+            return {
+                hint: `The app is ${label(c)}, and it imports a neighbour package of the workspace. ` +
+                    `--root ${c.dir} would upload the app without that package, so build it from this folder: ` +
+                    "a buildCommand that builds the neighbours first, and the app's output folder.",
+                next_action: `create layero.json here: ${JSON.stringify(recipe)} — then deploy from this folder`,
+                candidates,
+            };
+        }
+        return {
+            hint: `This folder has no app of its own${workspace ? " (it is a workspace root)" : ""}; the app is ${label(c)}. ` +
+                "Deploy that folder.",
+            next_action: `npx layero@latest deploy --root ${c.dir}`,
+            candidates,
+        };
+    }
+    if (apps.length > 1) {
+        return {
+            hint: `Several app folders: ${apps.map(label).join(", ")}. ` +
+                "One project deploys one of them — pick it with --root.",
+            next_action: `npx layero@latest deploy --root ${apps[0].dir}`,
+            candidates,
+        };
+    }
+    const build = scriptOf(pkg, "build");
+    if (build && plan.framework === "static") {
+        return {
+            hint: `package.json has a build script (\`${build}\`), but no known framework was recognised and there is no index.html at the root. ` +
+                "As it stands the platform serves these files as they are and does NOT run the build (framework \"static\").",
+            next_action: snap.layeroJson
+                ? 'if the site must be built, add "framework": "generic" to layero.json ' +
+                    "(buildCommand runs your script; outputDirectory is the folder that holds index.html after the build)"
+                : "if the site must be built, create layero.json: " +
+                    '{"framework":"generic","buildCommand":"npm run build","outputDirectory":"<folder that holds index.html after the build>"}',
+        };
+    }
+    if (build) {
+        return {
+            hint: `No known framework: the platform will run the build script (\`${build}\`) and serve the folder where index.html appears after the build. ` +
+                "If it lands somewhere unexpected, set outputDirectory in layero.json.",
+        };
+    }
+    const start = scriptOf(pkg, "start");
+    const serverEntry = await findServerEntry(cwd, pkg);
+    if (start || serverEntry) {
+        // Без скрипта `start` сборщик приложений перебирает свой список точек
+        // входа (server.js, index.js, …) и `server.mjs` не находит — одного
+        // `-t node_web` мало, команду запуска надо назвать (кейс a3).
+        return {
+            hint: `This looks like a Node server (${start ? `start script \`${start}\`` : `${serverEntry} calls listen()`}), ` +
+                "but no known server framework was recognised. A server has to be run in a container, not served as files.",
+            next_action: start
+                ? `npx layero@latest deploy -t node_web  (the start script runs the server)`
+                : `create layero.json: {"runtime":"node_web","startCommand":"node ${serverEntry}"}`,
+        };
+    }
+    if (snap.requirementsTxt !== null || snap.files.has("pyproject.toml")) {
+        const app = await findPythonApp(cwd);
+        if (app) {
+            // Детект платформы ищет точку входа только в корне (main.py, app.py…);
+            // приложение в пакете (`service/web.py`) он не видит. Кейс b3.
+            const cmd = app.kind === "wsgi"
+                ? `gunicorn ${app.target} --bind 0.0.0.0:$PORT`
+                : `uvicorn ${app.target} --host 0.0.0.0 --port $PORT`;
+            return {
+                hint: `A Python web app (${app.framework}) whose entry is not at the root: \`${app.target}\`. ` +
+                    "The platform looks for main.py / app.py at the root, so name the app and how to start it.",
+                next_action: `create layero.json: {"runtime":"python_web","startCommand":"${cmd}"}`,
+            };
+        }
+        return {
+            hint: "A Python project, but no known web framework or entry file was recognised.",
+            next_action: 'npx layero@latest deploy -t python_web  (or layero.json: {"runtime":"python_web","startCommand":"uvicorn <module>:<app> --host 0.0.0.0 --port $PORT"})',
+        };
+    }
+    return {
+        hint: "Nothing to build or serve was recognised here: no index.html, no build script, no server, no app in a subfolder.",
+        next_action: "run the command from the app's folder (or pass --root <dir>); ready-made files: npx layero@latest deploy --prebuilt <dir>",
+    };
+}
+/**
+ * Каталог результата, заданный ФЛАГОМ в скрипте сборки (`vite build --outDir
+ * public_html`). Детект читает конфиги, а не флаги, — сборщик без
+ * `outputDirectory` ищет в умолчании фреймворка и может отдать исходный
+ * `index.html` из корня вместо собранного. Кейс «слепого» агента b1.
+ */
+const OUTDIR_FLAG_RE = /(?:^|\s)--(?:outDir|out-dir|outdir|output-dir|dist-dir)(?:=|\s+)(["']?)([^\s"'&|;]+)\1/;
+function outDirFlag(pkg) {
+    const m = OUTDIR_FLAG_RE.exec(scriptOf(pkg, "build") ?? "");
+    return m ? m[2].replace(/^\.\//, "").replace(/\/+$/, "") || null : null;
+}
+const SERVER_ENTRY_CANDIDATES = ["server.js", "index.js", "app.js", "main.js", "server.mjs", "index.mjs"];
+// `api = FastAPI(`, `app = Flask(__name__)` — объект приложения на верхнем
+// уровне модуля. ASGI запускает uvicorn, WSGI — gunicorn.
+const PY_APP_RE = /^(\w+)\s*=\s*(FastAPI|Starlette|Flask|Quart|Litestar)\s*\(/m;
+const PY_ASGI = new Set(["FastAPI", "Starlette", "Quart", "Litestar"]);
+const PY_SKIP = new Set([".venv", "venv", "env", "node_modules", ".git", "__pycache__", "site-packages", "tests", "test"]);
+async function findPythonApp(cwd, maxDepth = 3) {
+    const found = [];
+    async function walk(rel, depth) {
+        if (depth > maxDepth || found.length > 3)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(path.join(cwd, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const child = rel ? `${rel}/${e.name}` : e.name;
+            if (e.isFile() && e.name.endsWith(".py")) {
+                const text = await readText(path.join(cwd, child));
+                const m = text ? PY_APP_RE.exec(text.slice(0, 64 * 1024)) : null;
+                if (m)
+                    found.push({ rel: child, name: m[1], framework: m[2] });
+            }
+            else if (e.isDirectory() && !PY_SKIP.has(e.name) && !e.name.startsWith(".")) {
+                await walk(child, depth + 1);
+            }
+        }
+    }
+    await walk("", 0);
+    // Одно приложение — называем; несколько — гадать, какое главное, не берёмся.
+    if (found.length !== 1)
+        return null;
+    const f = found[0];
+    const module = f.rel.replace(/\.py$/, "").replace(/\//g, ".").replace(/\.__init__$/, "");
+    return {
+        target: `${module}:${f.name}`,
+        framework: f.framework,
+        kind: PY_ASGI.has(f.framework) ? "asgi" : "wsgi",
+    };
+}
+const LISTEN_RE = /\.listen\s*\(|createServer\s*\(/;
+async function findServerEntry(cwd, pkg) {
+    const names = [...(typeof pkg?.main === "string" ? [pkg.main] : []), ...SERVER_ENTRY_CANDIDATES];
+    for (const n of names) {
+        const text = await readText(path.join(cwd, n));
+        if (text !== null && LISTEN_RE.test(text.slice(0, 64 * 1024)))
+            return n;
+    }
+    return null;
+}
+/** Первая папка с index.html, если в корне его нет, — по правилу сборщика
+ * (`discover_served_root`): мельчайшая, затем по алфавиту. */
+async function servedSubdir(cwd, maxDepth = 3) {
+    let best = null;
+    async function walk(rel, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(path.join(cwd, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        if (depth > 0 && entries.some((e) => e.isFile() && e.name === "package.json"))
+            return;
+        if (depth > 0 && entries.some((e) => e.isFile() && e.name.toLowerCase() === "index.html")) {
+            if (!best || depth < best.depth || (depth === best.depth && rel.localeCompare(best.rel) < 0)) {
+                best = { rel, depth };
+            }
+            return;
+        }
+        for (const e of entries) {
+            if (e.isDirectory() && !SCAN_SKIP.has(e.name) && !e.name.startsWith(".")) {
+                await walk(rel ? `${rel}/${e.name}` : e.name, depth + 1);
+            }
+        }
+    }
+    await walk("", 0);
+    return best ? best.rel : null;
+}
+function str(v) {
+    return typeof v === "string" && v.trim() ? v.trim() : null;
+}
+const BUILD_SOURCE = {
+    detected: "package.json",
+    default: "framework default",
+    guess: "framework default",
+    unknown: "none",
+};
+const OUTPUT_SOURCE = {
+    detected: "framework config",
+    default: "framework default",
+    guess: "framework default",
+    unknown: "none",
+};
 /**
  * Detect framework / build command / output directory from the project shape.
  * Identity now comes from the unified detect_core (the same spec the builder
- * and backend wizard use); this function only adapts the resulting BuildPlan
- * into the CLI's `Detected` shape and its conventions (SSR Next reports `.next`,
- * runtime apps report a `static` placeholder + runtime_kind).
+ * and backend wizard use); this function adapts the resulting BuildPlan into
+ * the CLI's `Detected` shape and says honestly how sure it is.
+ *
+ * 🚨 ЭТО ПОДСКАЗКА, А НЕ РЕШЕНИЕ. Решает сборщик: он видит архив целиком и на
+ * первой сборке применяет правила, которых в TS-ядре нет. До 18.09.2026 CLI
+ * отправлял свою догадку в настройки проекта, и она перебивала сборщик на
+ * каждой следующей сборке (`(from hint)`, `(from dashboard)` в логе у проекта,
+ * который никто не настраивал). Теперь `deploy` отправляет только то, что
+ * назвал человек, а этот результат — только показывает.
  */
-export async function detectProject(cwd) {
+export async function detectProject(cwd, opts = {}) {
     const snap = await snapshotFromDir(cwd);
-    const plan = dc.detect(snap);
+    const layero = snap.layeroJson;
+    const fileFramework = str(layero?.framework);
+    const outsideHint = fileFramework ? null : str(opts.frameworkHint);
+    const plan = dc.detect(snap, fileFramework ?? outsideHint);
+    const frameworkSource = fileFramework
+        ? "layero.json"
+        : outsideHint
+            ? (opts.hintSource ?? "--type")
+            : "detected";
     if (plan.runtimeKind !== null) {
+        const fromFile = layero !== null && (str(layero.runtime) !== null || plan.projectKind === "fullstack");
+        const sources = {
+            framework: (fromFile ? "layero.json" : frameworkSource),
+            build_cmd: "none",
+            output_dir: "none",
+        };
         if (plan.projectType === "ssr_next") {
             // SSR Next builds in the runtime-builder; surface the framework + the
             // `.next` dir the CLI has always reported (vestigial but expected).
             const [unit] = dc.detectFramework(snap, "nextjs");
+            const script = snap.packageJson?.scripts?.build;
             return {
                 framework_hint: "nextjs",
                 build_cmd: unit.buildCmd ?? "npx next build",
                 output_dir: ".next",
                 confident: true,
                 runtime_kind: "ssr_next",
+                sources: { ...sources, build_cmd: script ? "package.json" : "framework default", output_dir: "framework default" },
             };
         }
-        // node_web / python_web / streamlit / gradio → static placeholder; the
-        // container serves the app, the SPA pipeline is a no-op.
+        // node_web / python_web / streamlit / gradio / fullstack: the container
+        // serves the app, nothing is uploaded as static files from this plan.
         return {
-            framework_hint: "static",
-            build_cmd: "true",
-            output_dir: ".",
+            framework_hint: plan.framework,
+            build_cmd: null,
+            output_dir: null,
             confident: true,
             runtime_kind: plan.projectType,
+            sources,
+            ...(plan.projectKind === "fullstack"
+                ? { hint: "Full-stack layout from layero.json: the frontend is served as files, the backend runs in a container." }
+                : {}),
         };
     }
     const framework = plan.framework;
-    const build_cmd = plan.buildCmd ?? (framework === "static" ? "true" : "npm run build");
+    const fileBuild = str(layero?.build);
+    const fileOutput = str(layero?.output);
+    let buildCmd = plan.buildCmd;
+    let buildSource = BUILD_SOURCE[plan.fieldSources.build_cmd ?? "unknown"] ?? "none";
+    let outputDir = plan.outputDir;
+    let outputSource = OUTPUT_SOURCE[plan.fieldSources.output_dir ?? "unknown"] ?? "none";
+    // Фреймворк назван человеком (файл, `--type`, настройки) — это не догадка.
+    const declared = Boolean(fileFramework || outsideHint);
+    let confident = declared || plan.confident;
+    let shape = null;
+    const notes = [];
+    let flagNextAction;
+    if (framework === "static") {
+        // Статика не собирается НИКОГДА: команда сборки у неё не «true», а
+        // отсутствует. Заглушка `true` читалась как команда и уезжала в проект.
+        buildCmd = null;
+        buildSource = "none";
+        outputDir = ".";
+        outputSource = "detected";
+        const pkg = snap.packageJson;
+        const buildScript = scriptOf(pkg, "build");
+        if (await rootHasIndexHtml(cwd)) {
+            confident = true;
+            if (buildScript && !declared) {
+                notes.push(`package.json has a build script (\`${buildScript}\`), but a static site is served as it is and the script is not run. ` +
+                    'If it must run: layero.json {"framework":"generic","buildCommand":"npm run build","outputDirectory":"<folder>"}.');
+            }
+        }
+        else {
+            const sub = buildScript || fileOutput ? null : await servedSubdir(cwd);
+            if (sub) {
+                confident = true;
+                outputDir = sub;
+                notes.push(`index.html is not at the root: the platform serves ${sub}/.`);
+            }
+            else if (declared) {
+                if (!fileOutput) {
+                    notes.push("There is no index.html at the root of this folder, and a static site is served as it is: " +
+                        "point outputDirectory at the folder with index.html, or deploy ready-made files with --prebuilt <dir>.");
+                }
+            }
+            else {
+                confident = false;
+                shape = await shapeOf(cwd, snap, plan);
+            }
+        }
+        if (fileBuild) {
+            notes.push('layero.json sets buildCommand, but the framework is "static", which never builds: the command will NOT run. ' +
+                'Set "framework" in layero.json (for a custom build script: "generic").');
+        }
+    }
+    else {
+        if (fileBuild) {
+            buildCmd = fileBuild;
+            buildSource = "layero.json";
+        }
+        if (framework === "generic" && !declared) {
+            confident = false;
+            shape = await shapeOf(cwd, snap, plan);
+        }
+        const flagDir = fileOutput ? null : outDirFlag(snap.packageJson);
+        if (flagDir && flagDir !== outputDir) {
+            // План платформы положит результат не туда: она не читает флаги скрипта.
+            confident = false;
+            notes.push(`The build script sets the output folder with a flag (\`${flagDir}\`), which detection does not read: ` +
+                `without outputDirectory the platform looks in "${outputDir ?? "dist"}" and may serve the source index.html instead of the build.`);
+            flagNextAction = snap.layeroJson
+                ? `add "outputDirectory": "${flagDir}" to layero.json`
+                : `create layero.json: {"outputDirectory":"${flagDir}"}`;
+        }
+        if (framework === "generic" && buildCmd === null) {
+            // Собирать нечем — и каталог результата у такой папки не «dist по
+            // умолчанию», а неизвестен: умолчание фреймворка «Other» здесь вымысел.
+            outputDir = null;
+            outputSource = "none";
+        }
+    }
+    if (fileOutput) {
+        outputDir = fileOutput;
+        outputSource = "layero.json";
+    }
     const warning = ssrWarning(snap, framework);
+    const hint = [shape?.hint, ...notes].filter(Boolean).join(" ");
     return {
         framework_hint: framework,
-        build_cmd,
-        output_dir: plan.outputDir ?? ".",
-        confident: plan.confident,
+        build_cmd: buildCmd,
+        output_dir: outputDir,
+        confident,
+        sources: { framework: frameworkSource, build_cmd: buildSource, output_dir: outputSource },
+        ...(hint ? { hint } : {}),
+        ...(shape?.next_action ?? flagNextAction ? { next_action: shape?.next_action ?? flagNextAction } : {}),
+        ...(shape?.candidates?.length ? { candidates: shape.candidates } : {}),
         ...(warning ? { ssr_warning: warning } : {}),
     };
 }
+/** Событие `detected` — одно на `init`, `deploy` и `deploy --dry-run`. */
+export function detectedEvent(d) {
+    return {
+        event: "detected",
+        framework: d.framework_hint,
+        build_cmd: d.build_cmd,
+        output_dir: d.output_dir,
+        confident: d.confident,
+        sources: d.sources,
+        ...(d.runtime_kind ? { runtime_kind: d.runtime_kind } : {}),
+        ...(d.hint ? { hint: d.hint } : {}),
+        ...(d.next_action ? { next_action: d.next_action } : {}),
+        ...(d.candidates?.length ? { candidates: d.candidates } : {}),
+        ...(d.ssr_warning ? { ssr_warning: d.ssr_warning } : {}),
+    };
+}