@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/cli/dist/utils/shared-platform-postgres.js

@@ -0,0 +1,232 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DATABASE_MANAGEMENT_FEATURE, PROJECT_JSON } from "./constants.js";
+import { DEFAULT_ALWAYS_ENABLED_INFRA } from "./project-config-defaults.js";
+import { discoverResourcesFromRoot } from "./services.js";
+/**
+ * Shared platform Postgres start predicate.
+ *
+ * Both names mean the one shared platform Postgres Tilt resource `postgres`.
+ * The engine start path is selection-bounded (flisk up --only); verify/doctor
+ * evaluate the project resource set they already inspect (no flisk up filter).
+ * Both surfaces use this same predicate shape over their own resource set.
+ *
+ * Feature state is read from project.json **and** the generated Tiltfile /
+ * spec.master when present, because a stock `flisk up` focus pass expands
+ * CORE_INFRA → database-management even when project.json omits it.
+ *
+ * Spec: openspec/changes/dependson-starts-platform-postgres
+ */
+export const POSTGRES_DEPENDENCY_NAMES = ["postgres", DATABASE_MANAGEMENT_FEATURE];
+const PHASE_KEYS = ["pre_alpha", "alpha", "beta", "out_of_scope"];
+export function isSharedPlatformPostgresDependency(name) {
+    return POSTGRES_DEPENDENCY_NAMES.includes(name);
+}
+function readProjectJson(projectRoot) {
+    try {
+        return JSON.parse(readFileSync(join(projectRoot, ".tdk", PROJECT_JSON), "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readTextIfExists(path) {
+    try {
+        return existsSync(path) ? readFileSync(path, "utf-8") : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Finds `name = [ ... ]` and returns its quoted strings. Plain string scanning, not a RegExp built from the name.
+function parseStarlarkStringList(source, name) {
+    const skipSpaces = (at) => {
+        let i = at;
+        while (i < source.length && /\s/.test(source[i]))
+            i += 1;
+        return i;
+    };
+    let from = 0;
+    for (;;) {
+        const at = source.indexOf(name, from);
+        if (at === -1)
+            return undefined;
+        let i = skipSpaces(at + name.length);
+        if (source[i] === "=") {
+            i = skipSpaces(i + 1);
+            if (source[i] === "[") {
+                const end = source.indexOf("]", i + 1);
+                if (end === -1)
+                    return undefined;
+                return [...source.slice(i + 1, end).matchAll(/"([^"]+)"|'([^']+)'/g)].map((x) => x[1] ?? x[2] ?? "");
+            }
+        }
+        from = at + name.length;
+    }
+}
+function tiltfileAlwaysEnabledInfra(projectRoot) {
+    const path = join(projectRoot, ".tdk", ".tdk-out", "Tiltfile");
+    const text = readTextIfExists(path);
+    if (!text)
+        return undefined;
+    return parseStarlarkStringList(text, "ALWAYS_ENABLED_INFRA");
+}
+function specMasterHasDatabaseManagement(projectRoot) {
+    const path = join(projectRoot, ".tdk", ".tdk-out", "spec.master");
+    const text = readTextIfExists(path);
+    if (text === undefined)
+        return undefined;
+    // PRE_ALPHA/DEFAULTS style: "database-management": True
+    return /"database-management"\s*:\s*True/.test(text);
+}
+function generatedDefaultFocusEnablesDatabaseManagement(projectRoot) {
+    const output = join(projectRoot, ".tdk", ".tdk-out");
+    const tiltfile = readTextIfExists(join(output, "Tiltfile"));
+    const spec = readTextIfExists(join(output, "spec.master"));
+    const config = readTextIfExists(join(output, "tdk-cli-ext", "discovery", "config.star"));
+    const profiles = readTextIfExists(join(output, "tdk-cli-ext", "engine", "topologies", "tilt", "config", "profiles.star"));
+    if (!tiltfile || !spec || !config || !profiles)
+        return false;
+    const preAlpha = spec.match(/PRE_ALPHA_RESOURCES\s*=\s*\{([^}]*)\}/)?.[1];
+    const coreInfra = parseStarlarkStringList(config, "CORE_INFRA");
+    return (/FOCUS_MODE\s*,\s*FOCUS_ENABLED_ALL\s*,\s*FOCUS_ENABLED_RESOURCES\s*=\s*Config\.apply_focus\(cfg\)/.test(tiltfile) &&
+        /if FOCUS_MODE and FOCUS_ENABLED_ALL\s*:/.test(tiltfile) &&
+        /"[^"]+"\s*:\s*True|'[^']+'\s*:\s*True/.test(preAlpha ?? "") &&
+        (coreInfra?.includes("postgres") ?? false) &&
+        /["']postgres["']\s*:\s*["']database-management["']/.test(config) &&
+        /for infra in CORE_INFRA_EXPORT\s*:/.test(profiles) &&
+        /needed\[INFRA_STACK_MAP_EXPORT\[infra\]\]\s*=\s*True/.test(profiles));
+}
+function projectJsonFeatureOn(projectRoot) {
+    const parsed = readProjectJson(projectRoot);
+    if (!parsed)
+        return false;
+    const phases = (parsed.phases ?? {});
+    for (const phase of PHASE_KEYS) {
+        const stacks = phases[phase]?.enabledStacks;
+        if (Array.isArray(stacks) && stacks.includes(DATABASE_MANAGEMENT_FEATURE)) {
+            return true;
+        }
+    }
+    const alwaysEnabled = parsed.always_enabled_infra ?? DEFAULT_ALWAYS_ENABLED_INFRA;
+    return Array.isArray(alwaysEnabled) && alwaysEnabled.includes(DATABASE_MANAGEMENT_FEATURE);
+}
+/**
+ * True when database-management is on for this project from project.json
+ * **or** the generated Tiltfile/spec.master when those files exist.
+ */
+export function databaseManagementEnabled(projectRoot) {
+    if (projectJsonFeatureOn(projectRoot))
+        return true;
+    const fromTilt = tiltfileAlwaysEnabledInfra(projectRoot);
+    if (Array.isArray(fromTilt) && fromTilt.includes(DATABASE_MANAGEMENT_FEATURE))
+        return true;
+    if (specMasterHasDatabaseManagement(projectRoot) === true)
+        return true;
+    return false;
+}
+/** Known names for unknown-dependsOn detection: discovered services/stacks + project stacks/infra. */
+function knownDependsonNames(projectRoot, resources) {
+    const known = new Set();
+    for (const name of POSTGRES_DEPENDENCY_NAMES)
+        known.add(name);
+    for (const resource of resources) {
+        known.add(resource.name);
+        if (resource.stack)
+            known.add(resource.stack);
+    }
+    const parsed = readProjectJson(projectRoot);
+    if (parsed) {
+        const phases = (parsed.phases ?? {});
+        for (const phase of PHASE_KEYS) {
+            const stacks = phases[phase]?.enabledStacks;
+            if (Array.isArray(stacks)) {
+                for (const stack of stacks)
+                    known.add(stack);
+            }
+        }
+        const alwaysEnabled = parsed.always_enabled_infra ?? DEFAULT_ALWAYS_ENABLED_INFRA;
+        if (Array.isArray(alwaysEnabled)) {
+            for (const entry of alwaysEnabled)
+                known.add(entry);
+        }
+    }
+    const fromTilt = tiltfileAlwaysEnabledInfra(projectRoot);
+    if (Array.isArray(fromTilt)) {
+        for (const entry of fromTilt)
+            known.add(entry);
+    }
+    return known;
+}
+/**
+ * Evaluate whether shared platform Postgres will start for this project.
+ *
+ * willStart = featureOn OR any inspected project resource depends on either name.
+ * Resource set is project scope (discoverResourcesFromRoot), NOT flisk up --only.
+ *
+ * Also reports focusWouldEnableDatabaseManagement so doctor/verify can warn that
+ * default focus expands CORE_INFRA → database-management even when project.json
+ * says the feature is off (the 7.1 gap).
+ */
+export function evaluateSharedPlatformPostgres(projectRoot, resources = discoverResourcesFromRoot(projectRoot)) {
+    const featureOnFromProjectJson = projectJsonFeatureOn(projectRoot);
+    const fromTilt = tiltfileAlwaysEnabledInfra(projectRoot);
+    const featureOnFromTiltfile = Array.isArray(fromTilt) && fromTilt.includes(DATABASE_MANAGEMENT_FEATURE);
+    const featureOnFromSpecMaster = specMasterHasDatabaseManagement(projectRoot) === true;
+    const featureOn = featureOnFromProjectJson || featureOnFromTiltfile || featureOnFromSpecMaster;
+    const focusWouldEnableDatabaseManagement = !featureOnFromProjectJson && generatedDefaultFocusEnablesDatabaseManagement(projectRoot);
+    const known = knownDependsonNames(projectRoot, resources);
+    const dependsOnUsers = [];
+    const unknownDependsOnNames = [];
+    for (const resource of resources) {
+        const deps = resource.config?.dependsOn ?? [];
+        let usesSharedPostgres = false;
+        for (const dep of deps) {
+            if (isSharedPlatformPostgresDependency(dep)) {
+                usesSharedPostgres = true;
+                continue;
+            }
+            if (!known.has(dep)) {
+                unknownDependsOnNames.push({ resource: resource.name, name: dep });
+            }
+        }
+        if (usesSharedPostgres) {
+            dependsOnUsers.push(resource.name);
+        }
+    }
+    const willStart = featureOn || dependsOnUsers.length > 0;
+    const reason = featureOn
+        ? "feature"
+        : dependsOnUsers.length > 0
+            ? "dependsOn"
+            : "none";
+    return {
+        featureOn,
+        featureOnFromProjectJson,
+        featureOnFromTiltfile,
+        featureOnFromSpecMaster,
+        focusWouldEnableDatabaseManagement,
+        dependsOnUsers,
+        willStart,
+        reason,
+        unknownDependsOnNames,
+    };
+}
+/** Human-readable will-start / will-not-start sentence shared by doctor + verify. */
+export function sharedPlatformPostgresMessage(evaluation) {
+    const projectScopeNote = " (project resource set; flisk up may select a subset and not start Postgres)";
+    if (!evaluation.willStart) {
+        const focusNote = evaluation.focusWouldEnableDatabaseManagement
+            ? " Note: default focus/CORE_INFRA expansion would enable database-management on a typical flisk up even when project.json lists it off."
+            : "";
+        return `Shared platform Postgres will not start for this project.json/generated Tiltfile state (no database-management feature, no selected dependsOn).${focusNote}`;
+    }
+    const why = evaluation.reason === "feature"
+        ? `the database-management feature is enabled${evaluation.featureOnFromTiltfile || evaluation.featureOnFromSpecMaster
+            ? " (generated Tiltfile/spec.master)"
+            : ""}`
+        : `resource(s) ${evaluation.dependsOnUsers.join(", ")} depend on postgres/database-management`;
+    return `Shared platform Postgres will start because ${why}${projectScopeNote}`;
+}

package/cli/dist/utils/single-flight.js

@@ -0,0 +1,21 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+/**
+ * Runs a load and applies its result, but starts nothing while a previous load is still running. A poll on a timer
+ * therefore never overlaps itself: results cannot arrive out of order, and a slow Tilt cannot make every poll get
+ * superseded before it finishes.
+ */
+export function singleFlight(apply) {
+    let running = false;
+    return async (load) => {
+        if (running)
+            return;
+        running = true;
+        try {
+            apply(await load());
+        }
+        finally {
+            running = false;
+        }
+    };
+}

package/cli/dist/utils/smoke.js

@@ -0,0 +1,401 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { copyFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { BRING_YOUR_OWN_TYPE } from "./constants.js";
+import { isApiServiceType } from "./resource-kind.js";
+import { createEnvRedactor } from "./secret-redaction.js";
+import { resolveServicePath, resolveSubdomainBases } from "./service-urls.js";
+export const DEFAULT_SMOKE_TIMEOUT_SECONDS = 60;
+const RETRY_DELAY_MS = 1000;
+const REQUEST_TIMEOUT_MS = 10_000;
+const BODY_SNIPPET_CHARS = 200;
+/** Largest response body kept in a smoke record. */
+export const SMOKE_RECORD_BODY_MAX_BYTES = 64 * 1024;
+/** Statuses a proxy answers while a route or its upstream is not up yet. Anything else is the service's real answer. */
+const NOT_READY_STATUSES = new Set([404, 502, 503, 504]);
+/** Error codes that prove the request never left this machine, so repeating even a write is safe. */
+const PRE_SEND_ERROR_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+]);
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A thrown request error is retried for safe methods, and for others only when its code shows the request was never sent. */
+function shouldRetryRequestError(err, method) {
+    if (SAFE_METHODS.has(method))
+        return true;
+    if (!isRecord(err))
+        return false;
+    const cause = isRecord(err.cause) ? err.cause : undefined;
+    const code = err.code ?? cause?.code;
+    return typeof code === "string" && PRE_SEND_ERROR_CODES.has(code);
+}
+export function validateSmoke(smoke) {
+    if (!isRecord(smoke))
+        return ['smoke: must be an object with "via" and "steps"'];
+    const errors = [];
+    if (smoke.via !== "proxy") {
+        errors.push('smoke.via: only "proxy" is supported (the check must go through the public URL)');
+    }
+    if (smoke.timeoutSeconds !== undefined &&
+        !(typeof smoke.timeoutSeconds === "number" && smoke.timeoutSeconds > 0)) {
+        errors.push("smoke.timeoutSeconds: must be a number greater than 0");
+    }
+    if (!Array.isArray(smoke.steps) || smoke.steps.length === 0) {
+        errors.push("smoke.steps: needs at least one step");
+        return errors;
+    }
+    smoke.steps.forEach((step, index) => {
+        const at = `smoke.steps[${index}]`;
+        if (!isRecord(step)) {
+            errors.push(`${at}: must be an object`);
+            return;
+        }
+        const path = step.path;
+        if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//")) {
+            errors.push(`${at}.path: must start with "/" and is appended to the public URL; a full URL or relative path would skip the proxy`);
+        }
+        if (step.expect !== undefined &&
+            !(typeof step.expect === "number" &&
+                Number.isInteger(step.expect) &&
+                step.expect >= 100 &&
+                step.expect <= 599)) {
+            errors.push(`${at}.expect: must be an HTTP status between 100 and 599`);
+        }
+        if (step.bodyContains !== undefined && typeof step.bodyContains !== "string") {
+            errors.push(`${at}.bodyContains: must be a string`);
+        }
+        if (step.save !== undefined) {
+            const ok = isRecord(step.save) &&
+                Object.values(step.save).every((v) => typeof v === "string" && v.startsWith("$."));
+            if (!ok)
+                errors.push(`${at}.save: must map names to paths such as "$.id"`);
+        }
+    });
+    return errors;
+}
+/** One plan per routable service that declares `smoke`. Workers and BYO with exposeViaProxy false have no public route. */
+export function buildSmokePlans(resources, ingressPort) {
+    const { appBase, apiBase } = resolveSubdomainBases(ingressPort);
+    const plans = [];
+    for (const resource of resources) {
+        const config = resource.config;
+        if (!config?.smoke)
+            continue;
+        const appType = config.appType;
+        const isApi = isApiServiceType(appType) || appType === BRING_YOUR_OWN_TYPE;
+        if (!isApi && appType !== "frontend")
+            continue;
+        if (config.exposeViaProxy === false)
+            continue;
+        const base = isApi ? apiBase : appBase;
+        // The container healthcheck path (default /health for APIs) is the one request that is safe to repeat while the route comes up.
+        const readyPath = config.healthCheckPath || (isApi && appType !== BRING_YOUR_OWN_TYPE ? "/health" : undefined);
+        plans.push({
+            name: resource.name,
+            baseUrl: `${base}${resolveServicePath(resource).replace(/\/+$/, "")}`,
+            ...(readyPath?.startsWith("/") ? { readyPath } : {}),
+            smoke: config.smoke,
+        });
+    }
+    return plans;
+}
+/** Caps each read-only smoke check so a doctor run cannot wait the full `flisk up` budget per service. */
+const DOCTOR_SMOKE_TIMEOUT_SECONDS = 10;
+/**
+ * The GET-only part of each smoke block, for `flisk doctor`. Doctor must never write to a service, and a step whose path reads
+ * a value saved by an earlier write (`{{name}}`) cannot run on its own, so both are dropped. A service with no such steps is left out.
+ * `bodyContains` is also cleared: it asserts on data that earlier writes created, so doctor would fail a healthy route whose data was removed.
+ * The status check stays, which is what shows a route exists.
+ */
+export function readOnlySmokePlans(plans, options = {}) {
+    const cap = options.timeoutSeconds ?? DOCTOR_SMOKE_TIMEOUT_SECONDS;
+    return plans.flatMap((plan) => {
+        const steps = plan.smoke.steps
+            .filter((step) => (step.method ?? "GET").toUpperCase() === "GET" &&
+            step.body === undefined &&
+            !step.path.includes("{{"))
+            .map((step) => ({ ...step, bodyContains: undefined }));
+        if (steps.length === 0)
+            return [];
+        const budget = Math.min(plan.smoke.timeoutSeconds ?? DEFAULT_SMOKE_TIMEOUT_SECONDS, cap);
+        return [
+            {
+                name: plan.name,
+                baseUrl: plan.baseUrl,
+                smoke: { via: plan.smoke.via, timeoutSeconds: budget, steps },
+            },
+        ];
+    });
+}
+function readPath(value, path) {
+    const parts = path.replace(/^\$\.?/, "").match(/[^.[\]]+/g) ?? [];
+    let current = value;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        // Own properties only: a path like "__proto__" must not reach inherited values.
+        if (part === "__proto__" || part === "constructor" || part === "prototype")
+            return undefined;
+        if (!Object.hasOwn(current, part))
+            return undefined;
+        // Resolve only own data properties. Besides avoiding inherited properties, this
+        // avoids invoking accessors on values supplied by smoke-test responses.
+        const descriptor = Object.getOwnPropertyDescriptor(current, part);
+        if (!descriptor || !("value" in descriptor))
+            return undefined;
+        current = descriptor.value;
+    }
+    return current;
+}
+function fill(template, saved) {
+    return template.replace(/\{\{(\w+)\}\}/g, (match, key) => saved[key] ?? match);
+}
+function fillBody(body, saved) {
+    if (typeof body === "string")
+        return fill(body, saved);
+    if (Array.isArray(body))
+        return body.map((item) => fillBody(item, saved));
+    if (isRecord(body)) {
+        return Object.fromEntries(Object.entries(body).map(([k, v]) => [k, fillBody(v, saved)]));
+    }
+    return body;
+}
+function snippet(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > BODY_SNIPPET_CHARS ? `${flat.slice(0, BODY_SNIPPET_CHARS)}...` : flat;
+}
+function slug(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "step");
+}
+/** Two steps whose names slug the same (`read back`, `read-back`) must not share a record directory. */
+function stepKey(seen, label) {
+    const base = slug(label);
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    return n === 1 ? base : `${base}-${n}`;
+}
+/** Writes latest.json (+ body.txt) for a step; a passing step also replaces the last-success pair. Returns the latest.json path. */
+function writeStepRecord(recordDir, stepKey, record, body, passed) {
+    try {
+        const dir = join(recordDir, slug(record.service), stepKey);
+        mkdirSync(dir, { recursive: true });
+        const latest = join(dir, "latest.json");
+        const bodyPath = join(dir, "body.txt");
+        if (body === undefined) {
+            rmSync(bodyPath, { force: true });
+        }
+        else {
+            writeFileSync(bodyPath, body);
+        }
+        writeFileSync(latest, `${JSON.stringify({ ...record, bodyPath: body === undefined ? null : "body.txt" }, null, 2)}\n`);
+        if (passed) {
+            copyFileSync(latest, join(dir, "last-success.json"));
+            if (body === undefined)
+                rmSync(join(dir, "last-success-body.txt"), { force: true });
+            else
+                copyFileSync(bodyPath, join(dir, "last-success-body.txt"));
+        }
+        return latest;
+    }
+    catch {
+        // The record is a diagnostic aid; failing to write it must not change the smoke result.
+        return undefined;
+    }
+}
+/** Caps a body at SMOKE_RECORD_BODY_MAX_BYTES of UTF-8 without splitting a character. */
+function capBody(text) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= SMOKE_RECORD_BODY_MAX_BYTES)
+        return { body: text, truncated: false, bytes: buf.length };
+    const body = buf
+        .subarray(0, SMOKE_RECORD_BODY_MAX_BYTES)
+        .toString("utf8")
+        .replace(/\uFFFD$/, "");
+    return { body, truncated: true, bytes: Buffer.byteLength(body, "utf8") };
+}
+/** Runs the steps in order. A not-ready answer (connection error, 404, 502-504) is retried until the timeout; a real wrong answer fails at once. */
+export async function runSmokePlan(plan, deps = {}) {
+    const doFetch = deps.fetch ?? ((url, init) => fetch(url, init));
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const budgetMs = (plan.smoke.timeoutSeconds ?? DEFAULT_SMOKE_TIMEOUT_SECONDS) * 1000;
+    let deadline = now() + budgetMs;
+    const saved = {};
+    // A manifest with errors is still loaded, so a malformed block must fail the check, not throw out of `flisk up`.
+    const invalid = validateSmoke(plan.smoke);
+    if (invalid.length > 0) {
+        return {
+            name: plan.name,
+            ok: false,
+            failure: `${plan.name}: invalid smoke block: ${invalid.join("; ")}`,
+        };
+    }
+    // `flisk up` starts the check once Tilt's UI is up, while images may still be building. Traefik then resets or 404s early requests.
+    // A write must not be repeated after a reset (it may have reached the service), so wait for readiness with GETs instead.
+    // If the service never answers, fall through: the first step then fails with its own record.
+    if (plan.readyPath) {
+        const readyUrl = `${plan.baseUrl}${plan.readyPath}`;
+        for (;;) {
+            try {
+                const response = await doFetch(readyUrl, {
+                    method: "GET",
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                await response.text();
+                // A 5xx from the health path (migrations running, database not up) is still "not ready"; 401 or 3xx means something answered.
+                if (!NOT_READY_STATUSES.has(response.status) && response.status < 500)
+                    break;
+            }
+            catch {
+                // not accepting connections yet
+            }
+            if (now() >= deadline)
+                break;
+            await sleep(RETRY_DELAY_MS);
+        }
+    }
+    // The steps get their own `timeoutSeconds`; a slow build must not eat the first step's budget.
+    deadline = now() + budgetMs;
+    const stepKeys = new Map();
+    for (const [index, step] of plan.smoke.steps.entries()) {
+        const label = step.name ?? `step ${index + 1}`;
+        const method = (step.method ?? "GET").toUpperCase();
+        const url = `${plan.baseUrl}${fill(step.path, saved)}`;
+        const expected = step.expect ?? 200;
+        const hasBody = step.body !== undefined;
+        let status;
+        let text = "";
+        let error;
+        let errorCode;
+        for (;;) {
+            error = undefined;
+            errorCode = undefined;
+            status = undefined;
+            let retryableError = false;
+            try {
+                const response = await doFetch(url, {
+                    method,
+                    headers: hasBody ? { "content-type": "application/json" } : undefined,
+                    body: hasBody ? JSON.stringify(fillBody(step.body, saved)) : undefined,
+                    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                });
+                status = response.status;
+                text = await response.text();
+            }
+            catch (err) {
+                retryableError = shouldRetryRequestError(err, method);
+                error = err instanceof Error ? err.message : String(err);
+                const code = isRecord(err)
+                    ? (err.code ?? (isRecord(err.cause) ? err.cause.code : undefined))
+                    : undefined;
+                errorCode = typeof code === "string" ? code : undefined;
+            }
+            const notReady = (error !== undefined && retryableError) ||
+                (status !== undefined && status !== expected && NOT_READY_STATUSES.has(status));
+            if (!notReady || now() >= deadline)
+                break;
+            await sleep(RETRY_DELAY_MS);
+        }
+        // The URL, the response body and the error can all hold a secret the project knows about. Mask them once, here, so the
+        // printed snippet, the stored body and the record cannot drift apart. The raw text still decides the assertions and the
+        // saved values: masking is for what is shown and stored, not for what is checked or sent.
+        let maskFailed = false;
+        const mask = (text) => {
+            if (maskFailed)
+                return undefined;
+            if (!deps.redact)
+                return text;
+            try {
+                return deps.redact(text);
+            }
+            catch (error) {
+                maskFailed = true;
+                const reason = error instanceof Error ? error.message : String(error);
+                deps.warn?.(`${plan.name}: ${label}: the response text was neither shown nor stored: ${reason}`);
+                return undefined;
+            }
+        };
+        const safeUrl = mask(url);
+        const safeText = status === undefined ? undefined : mask(text);
+        const safeError = error === undefined ? undefined : mask(error);
+        const recordError = error === undefined ? undefined : (errorCode ?? safeError);
+        const where = `${plan.name}: ${label}: ${method} ${safeUrl ?? "(url withheld)"}`;
+        // Every step that ran leaves a record. A step is "passed" for last-success only if status and bodyContains both match.
+        let recordPath;
+        if (deps.recordDir) {
+            const capped = safeText === undefined ? undefined : capBody(safeText);
+            const passed = error === undefined &&
+                status === expected &&
+                (step.bodyContains === undefined || text.includes(step.bodyContains));
+            recordPath = writeStepRecord(deps.recordDir, stepKey(stepKeys, label), {
+                service: plan.name,
+                step: label,
+                method,
+                ...(safeUrl === undefined ? {} : { url: safeUrl }),
+                expectedStatus: expected,
+                status: status ?? null,
+                ...(recordError === undefined ? {} : { error: recordError }),
+                truncated: capped?.truncated ?? false,
+                bodyBytes: capped?.bytes ?? 0,
+            }, capped?.body, passed);
+        }
+        const fail = (failure) => ({
+            name: plan.name,
+            ok: false,
+            failure,
+            recordPath,
+        });
+        if (error !== undefined)
+            return fail(`${where} never answered (${safeError ?? "the error was withheld"})`);
+        if (status !== expected) {
+            return fail(`${where} returned ${status}, expected ${expected}${safeText ? `: ${snippet(safeText)}` : ""}`);
+        }
+        if (step.bodyContains !== undefined && !text.includes(step.bodyContains)) {
+            return fail(`${where} returned ${status} but the body does not contain "${step.bodyContains}"${safeText ? `: ${snippet(safeText)}` : ""}`);
+        }
+        if (step.save) {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                return fail(`${where} returned a body that is not JSON, cannot save${safeText ? `: ${snippet(safeText)}` : ""}`);
+            }
+            for (const [key, path] of Object.entries(step.save)) {
+                const value = readPath(parsed, path);
+                if (value === undefined || value === null || typeof value === "object") {
+                    return fail(`${where} response has no ${path} to save as {{${key}}}${safeText ? `: ${snippet(safeText)}` : ""}`);
+                }
+                saved[key] = String(value);
+            }
+        }
+    }
+    return { name: plan.name, ok: true };
+}
+export function formatSmokeFailure(result) {
+    return `Smoke check failed: ${result.failure}${result.recordPath ? ` (record: ${result.recordPath})` : ""}`;
+}
+/**
+ * The dependencies that keep smoke text safe: the project's own secret values are masked before anything is shown or stored.
+ * Both `flisk up` and `flisk doctor` use them, so neither prints a body that holds a secret.
+ */
+export function safeSmokeDeps(projectRoot, warn) {
+    return {
+        redact: createEnvRedactor(projectRoot),
+        ...(warn ? { warn } : {}),
+    };
+}
+/** Runs every plan side by side; each plan keeps its own timeout. */
+export async function runSmokePlans(plans, deps = {}) {
+    return Promise.all(plans.map((plan) => runSmokePlan(plan, deps)));
+}