@flisk-sh/flisk 0.0.0-stage → 1.3.190

package/cli/dist/utils/schema-version-gate.js

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { relative } from "node:path";
+import chalk from "chalk";
+import { formatCount } from "./formatting.js";
+import { SERVICE_MANIFEST_SCHEMA_VERSION } from "./service-manifest.js";
+import { discoverResourcesFromRoot } from "./services.js";
+/**
+ * A service.json that declares a schemaVersion this flisk does not know is refused before anything starts: a newer format
+ * read as if it were the old one could start the wrong thing. A missing schemaVersion is not refused (see
+ * warnSchemaVersions), because every project began without one.
+ */
+export function enforceSchemaVersionGate(projectRoot, options = {}, exit = process.exit) {
+    // A root that cannot be read is reported by the checks that run next; this gate only refuses what it can read.
+    let resources;
+    if (options.resources) {
+        resources = options.resources;
+    }
+    else {
+        try {
+            resources = discoverResourcesFromRoot(projectRoot);
+        }
+        catch {
+            return;
+        }
+    }
+    const unsupported = resources.flatMap((resource) => {
+        const version = resource.config?.schemaVersion;
+        if (version === undefined || version === SERVICE_MANIFEST_SCHEMA_VERSION)
+            return [];
+        const file = relative(projectRoot, resource.configPath) || resource.configPath;
+        return [
+            `${file} schemaVersion ${JSON.stringify(version)}: this flisk supports ${SERVICE_MANIFEST_SCHEMA_VERSION}`,
+        ];
+    });
+    if (unsupported.length === 0)
+        return;
+    const verb = unsupported.length === 1 ? "declares" : "declare";
+    const message = `${formatCount(unsupported.length, "service.json file")} ${verb} a schemaVersion this flisk does not support:\n    ${unsupported.join("\n    ")}`;
+    const fix = "Upgrade flisk to a version that supports these files. Changing schemaVersion by hand is not a fix";
+    options.onInvalid?.(`${message}\nFix: ${fix}`);
+    console.error(chalk.red(`✗ ${message}`));
+    console.error(chalk.gray(`  Fix: ${fix}`));
+    exit(1);
+}

package/cli/dist/utils/search-status.js

@@ -0,0 +1,12 @@
+/** Describes a `/` search result for the `flisk ui` header; null when there is no query. */
+export function describeSearch(query, matches, total) {
+    if (!query)
+        return null;
+    if (matches === 0) {
+        return {
+            summary: "0 matches",
+            emptyMessage: `No resources match "${query}". Press Esc to clear.`,
+        };
+    }
+    return { summary: `${matches} of ${total}` };
+}

package/cli/dist/utils/secret-redaction.js

@@ -0,0 +1,73 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseEnv } from "./env-validator.js";
+export const REDACTED = "[REDACTED]";
+export class EnvUnreadableError extends Error {
+    path;
+    constructor(path, reason) {
+        super(`Could not read ${path}: ${reason}`);
+        this.path = path;
+        this.name = "EnvUnreadableError";
+    }
+}
+/**
+ * Shorter values are left alone: masking a two-letter value would hit ordinary words in every log line. The cost is
+ * that a short secret in .env is not masked, so keep real secrets at least this long.
+ */
+export const MIN_REDACTED_VALUE_LENGTH = 8;
+/**
+ * Values of the project's own .env file, longest first so a value that contains another is masked whole. Throws when the
+ * file exists but cannot be read: continuing without the values would print secrets unmasked.
+ */
+export function envSecretValues(projectRoot) {
+    const envPath = join(projectRoot, ".env");
+    if (!existsSync(envPath))
+        return [];
+    let content;
+    try {
+        content = readFileSync(envPath, "utf-8");
+    }
+    catch (error) {
+        throw new EnvUnreadableError(envPath, error instanceof Error ? error.message : String(error));
+    }
+    const values = [...parseEnv(content).values()].filter((value) => value.length >= MIN_REDACTED_VALUE_LENGTH);
+    return [...new Set(values)].sort((a, b) => b.length - a.length);
+}
+export function redactSecrets(text, secrets) {
+    let result = text;
+    for (const secret of secrets)
+        result = result.split(secret).join(REDACTED);
+    return result;
+}
+/** Redacts every string inside a JSON-shaped value, so the output stays valid JSON. */
+export function redactValue(value, secrets) {
+    if (secrets.length === 0)
+        return value;
+    if (typeof value === "string")
+        return redactSecrets(value, secrets);
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item, secrets));
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactValue(item, secrets)]));
+    }
+    return value;
+}
+/**
+ * A redactor for text that may hold the project's own secrets. When the project's .env exists but cannot be read, the values
+ * are unknown, so the redactor throws instead of guessing: the caller then shows and stores nothing rather than raw text. The
+ * original error is kept, so a caller can still tell an unreadable .env from another failure.
+ */
+export function createEnvRedactor(projectRoot) {
+    let secrets;
+    try {
+        secrets = envSecretValues(projectRoot);
+    }
+    catch (error) {
+        return () => {
+            throw error;
+        };
+    }
+    return (text) => redactSecrets(text, secrets);
+}

package/cli/dist/utils/service-config-checks.js

@@ -0,0 +1,189 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { relative } from "node:path";
+import chalk from "chalk";
+import { checkDuplicateResourceNames } from "./doctor-wiring.js";
+import { formatCount } from "./formatting.js";
+import { findProjectRoot } from "./paths.js";
+import { SERVICE_MANIFEST_SCHEMA_VERSION } from "./service-manifest.js";
+import { discoverResourcesFromRoot } from "./services.js";
+function filePath(projectRoot, resource) {
+    return relative(projectRoot, resource.configPath) || resource.configPath;
+}
+/** The dependsOn names a service declares: none when absent, null when it is not an array of strings. */
+function declaredDependsOn(resource) {
+    const value = resource.config?.dependsOn;
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value) && value.every((entry) => typeof entry === "string"))
+        return value;
+    return null;
+}
+/** Each cycle once, as service names starting from the alphabetically first, ending where it started. */
+function findDependencyCycles(resources) {
+    const known = new Set(resources.map((r) => r.name));
+    const edges = new Map(resources.map((r) => [r.name, (declaredDependsOn(r) ?? []).filter((dep) => known.has(dep))]));
+    const cycles = new Map();
+    const state = new Map();
+    const stack = [];
+    const visit = (name) => {
+        state.set(name, "visiting");
+        stack.push(name);
+        for (const dep of edges.get(name) ?? []) {
+            if (state.get(dep) === "visiting") {
+                const loop = stack.slice(stack.indexOf(dep));
+                const start = loop.indexOf([...loop].sort()[0] ?? dep);
+                const ordered = [...loop.slice(start), ...loop.slice(0, start)];
+                cycles.set(ordered.join(">"), [...ordered, ordered[0] ?? dep]);
+            }
+            else if (!state.has(dep)) {
+                visit(dep);
+            }
+        }
+        stack.pop();
+        state.set(name, "done");
+    };
+    for (const name of [...edges.keys()].sort()) {
+        if (!state.has(name))
+            visit(name);
+    }
+    return [...cycles.values()];
+}
+/** A dependsOn that is not a list of service names cannot be followed, so say so instead of failing later. */
+export function checkDependsOnShape(projectRoot = findProjectRoot() ?? process.cwd(), resources = discoverResourcesFromRoot(projectRoot)) {
+    const problems = resources.flatMap((resource) => declaredDependsOn(resource) === null
+        ? [
+            `${filePath(projectRoot, resource)} dependsOn ${JSON.stringify(resource.config?.dependsOn)}: expected an array of service names`,
+        ]
+        : []);
+    if (problems.length === 0) {
+        return {
+            name: "dependsOn",
+            didPass: true,
+            message: "Every dependsOn is a list of service names",
+        };
+    }
+    return {
+        name: "dependsOn",
+        didPass: false,
+        message: `${formatCount(problems.length, "invalid dependsOn", "invalid dependsOn")}:\n    ${problems.join("\n    ")}`,
+        fix: 'Write "dependsOn" as an array of service names, for example ["postgres", "api"]',
+    };
+}
+/** Services that wait on each other can never both start. A dependsOn name that is not a service is left to the unknown-name check. */
+export function checkCircularDependencies(projectRoot = findProjectRoot() ?? process.cwd(), resources = discoverResourcesFromRoot(projectRoot)) {
+    const byName = new Map(resources.map((r) => [r.name, r]));
+    const cycles = findDependencyCycles(resources);
+    if (cycles.length === 0) {
+        return {
+            name: "Circular dependencies",
+            didPass: true,
+            message: "No service depends on itself through dependsOn",
+        };
+    }
+    const lines = cycles.map((cycle) => {
+        const first = byName.get(cycle[0] ?? "");
+        const next = cycle[1] ?? "";
+        return `${first ? filePath(projectRoot, first) : cycle[0]} dependsOn "${next}": circular dependency ${cycle.join(" -> ")}`;
+    });
+    return {
+        name: "Circular dependencies",
+        didPass: false,
+        message: `${cycles.length} ${cycles.length === 1 ? "circular dependency" : "circular dependencies"}:\n    ${lines.join("\n    ")}`,
+        fix: 'Remove one "dependsOn" entry in each cycle so the services no longer wait on each other, or move what they share into a third service',
+    };
+}
+/** A port outside 1-65535 can never be bound, and `flisk up` would otherwise find out only when Docker fails. */
+export function checkServicePorts(projectRoot = findProjectRoot() ?? process.cwd(), resources = discoverResourcesFromRoot(projectRoot)) {
+    const problems = resources.flatMap((resource) => {
+        const port = resource.config?.port;
+        if (port === undefined)
+            return [];
+        if (typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65535)
+            return [];
+        return [
+            `${filePath(projectRoot, resource)} port ${JSON.stringify(port)}: not an integer from 1 to 65535`,
+        ];
+    });
+    if (problems.length === 0) {
+        return { name: "Service ports", didPass: true, message: "Every declared port is valid" };
+    }
+    return {
+        name: "Service ports",
+        didPass: false,
+        message: `${formatCount(problems.length, "invalid port")}:\n    ${problems.join("\n    ")}`,
+        fix: 'Set "port" to the port the service listens on, an integer from 1 to 65535',
+    };
+}
+/**
+ * A service.json with no schemaVersion is how every project began, so this is a warning: it keeps working, and only
+ * `flisk config migrate` writes the field. A version this flisk does not know is reported the same way, with a different fix.
+ */
+export function checkSchemaVersions(projectRoot = findProjectRoot() ?? process.cwd(), strict = false, resources = discoverResourcesFromRoot(projectRoot)) {
+    const missing = [];
+    const unsupported = [];
+    for (const resource of resources) {
+        const version = resource.config?.schemaVersion;
+        if (version === SERVICE_MANIFEST_SCHEMA_VERSION)
+            continue;
+        const file = filePath(projectRoot, resource);
+        if (version === undefined)
+            missing.push(`${file} schemaVersion: missing`);
+        else
+            unsupported.push(`${file} schemaVersion ${JSON.stringify(version)}: this flisk supports ${SERVICE_MANIFEST_SCHEMA_VERSION}`);
+    }
+    if (missing.length === 0 && unsupported.length === 0) {
+        return {
+            name: "schemaVersion",
+            didPass: true,
+            message: "Every service.json has a supported schemaVersion",
+        };
+    }
+    const fixes = [
+        ...(missing.length > 0 ? ["Run `flisk config migrate` to add the missing schemaVersion"] : []),
+        ...(unsupported.length > 0
+            ? ["A version this flisk does not support cannot be migrated: upgrade flisk"]
+            : []),
+    ];
+    return {
+        name: "schemaVersion",
+        didPass: false,
+        isWarning: !strict,
+        message: `${formatCount(missing.length + unsupported.length, "service.json file")} without a supported schemaVersion:\n    ${[...missing, ...unsupported].join("\n    ")}`,
+        fix: fixes.join(". "),
+    };
+}
+/** Prints the schemaVersion warning once. It never stops anything: the project keeps working as it is. */
+export function warnSchemaVersions(projectRoot, resources) {
+    const check = checkSchemaVersions(projectRoot, false, resources);
+    if (check.didPass)
+        return;
+    console.warn(chalk.yellow(`⚠ ${check.message}`));
+    if (check.fix)
+        console.warn(chalk.gray(`  ${check.fix}`));
+}
+/**
+ * Runs before anything starts (also under --dry-run, like the drift gate): duplicate service names, circular
+ * dependsOn and invalid ports exit with 1 and say which file, which field, and how to fix it.
+ */
+export function enforceServiceConfigGate(projectRoot, options = {}, exit = process.exit) {
+    const resources = options.resources ?? discoverResourcesFromRoot(projectRoot);
+    const failed = [
+        checkDuplicateResourceNames(projectRoot, resources),
+        checkDependsOnShape(projectRoot, resources),
+        checkCircularDependencies(projectRoot, resources),
+        checkServicePorts(projectRoot, resources),
+    ].filter((check) => !check.didPass);
+    if (failed.length === 0)
+        return;
+    const text = failed
+        .map((check) => `${check.message}${check.fix ? `\nFix: ${check.fix}` : ""}`)
+        .join("\n");
+    options.onInvalid?.(text);
+    for (const check of failed) {
+        console.error(chalk.red(`✗ ${check.message}`));
+        if (check.fix)
+            console.error(chalk.gray(`  Fix: ${check.fix}`));
+    }
+    exit(1);
+}

package/cli/dist/utils/service-manifest.js

@@ -0,0 +1,254 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, readFileSync } from "node:fs";
+import { validateSmoke } from "./smoke.js";
+export const SERVICE_MANIFEST_SCHEMA_VERSION = 1;
+export const SERVICE_MANIFEST_SCHEMA_URL = "https://tdk-landscape.github.io/schema.service.json";
+/**
+ * Fields that are still read, or still tolerated, but should not be used. The warning says what replaces each one. `jwtSecret` is
+ * ignored outright: a secret must not be committed (see docs/environment.md).
+ */
+const DEPRECATED_FIELDS = {
+    dependencies: "deprecated, use dependsOn (still read for now)",
+    envVars: "deprecated, use params (still read when params is absent)",
+    jwtSecret: "ignored. A secret must not be committed: remove it and set JWT_SECRET in the project .env",
+};
+const KNOWN_SERVICE_FIELDS = new Set([
+    "$schema",
+    "agent",
+    "apiBasePath",
+    "apiPath",
+    "appName",
+    "appType",
+    "backendName",
+    "basePath",
+    "build",
+    "buildContext",
+    "databaseName",
+    "dependencies",
+    "dev",
+    "dependsOn",
+    "dockerfile",
+    "enabled",
+    "exposeViaProxy",
+    "featuresEnabled",
+    "framework",
+    "healthCheckPath",
+    "image",
+    "language",
+    "name",
+    "nats",
+    "params",
+    "playwright",
+    "port",
+    "replicas",
+    "restart",
+    "runtime",
+    "sablier",
+    "schemaVersion",
+    "secrets",
+    "smoke",
+    "stack",
+    "syncs",
+    "traefik",
+    "type",
+]);
+/**
+ * String fields written into the generated Docker Compose, Traefik and NATS config as they are. A newline or YAML syntax in one of
+ * them adds keys to the generated service (GHSA-phgf-pww4-7jxc), so each must match its pattern. Empty values are treated as unset.
+ * `tilt up` reads service.json without this CLI, so engine/topologies/tilt/manifest/parser.star enforces the same rules.
+ */
+const GENERATED_STRING_FIELDS = [
+    { path: ["healthCheckPath"], pattern: /^\/[a-z0-9/-]*$/, expected: "a path such as /health" },
+    {
+        path: ["traefik", "host"],
+        pattern: /^[A-Za-z0-9.-]+$/,
+        expected: "a hostname such as shop.backend.myproject.local",
+    },
+    {
+        path: ["traefik", "pathPrefix"],
+        pattern: /^\/[a-z0-9/-]*$/,
+        expected: "a path such as /api/v1/shop-management",
+    },
+    {
+        path: ["traefik", "healthCheck"],
+        pattern: /^\/[a-z0-9/-]*$/,
+        expected: "a path such as /health",
+    },
+    {
+        path: ["nats", "queueGroup"],
+        pattern: /^[A-Za-z0-9_.-]+$/,
+        expected: "letters, digits, '_', '.' or '-'",
+    },
+    { path: ["databaseName"], pattern: /^[A-Za-z0-9_-]+$/, expected: "letters, digits, '_' or '-'" },
+    { path: ["stack"], pattern: /^[A-Za-z0-9_-]+$/, expected: "letters, digits, '_' or '-'" },
+    {
+        path: ["image"],
+        pattern: /^[A-Za-z0-9._/:@-]+$/,
+        expected: "an image reference such as ghcr.io/acme/app:1.0",
+    },
+];
+/**
+ * Errors for generated-output fields whose values could change the generated YAML. The value itself is not echoed, because it may
+ * contain the newline that makes it dangerous.
+ */
+export function validateGeneratedStringFields(manifest, displayPath) {
+    const errors = [];
+    const reportedFields = new Set();
+    for (const { path, pattern, expected } of GENERATED_STRING_FIELDS) {
+        let value = manifest;
+        for (const key of path) {
+            value =
+                value && typeof value === "object" && !Array.isArray(value)
+                    ? value[key]
+                    : undefined;
+        }
+        if (value === undefined || value === null || value === "")
+            continue;
+        const field = `${displayPath}.${path.join(".")}`;
+        if (typeof value !== "string" || !pattern.test(value))
+            reportedFields.add(field);
+        if (typeof value !== "string") {
+            errors.push(`${field}: expected a string`);
+        }
+        else if (!pattern.test(value)) {
+            errors.push(`${field}: must be ${expected} (no spaces, line breaks or YAML syntax)`);
+        }
+    }
+    for (const [field, message] of lineBreakErrors(manifest, displayPath)) {
+        if (!reportedFields.has(field))
+            errors.push(`${field}: ${message}`);
+    }
+    return errors;
+}
+/** Line breaks (including the Unicode ones YAML 1.1 honours) and other control characters. */
+function hasLineBreakOrControl(text) {
+    for (let index = 0; index < text.length; index++) {
+        const code = text.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f || code === 0x85 || code === 0x2028 || code === 0x2029) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Many more service.json values than GENERATED_STRING_FIELDS reach the generated YAML (port, appName, dockerfile, buildContext,
+ * basePath, envVars, ...). A key can only be added through a line break, so no string key or value may contain one. `smoke` is
+ * skipped: the CLI sends it over HTTP and it is never written into generated config.
+ */
+function lineBreakErrors(manifest, displayPath) {
+    const errors = [];
+    const pending = Object.entries(manifest)
+        .filter(([key]) => key !== "smoke")
+        .map(([key, value]) => [value, `${displayPath}.${key}`]);
+    for (const key of Object.keys(manifest)) {
+        if (hasLineBreakOrControl(key))
+            errors.push([displayPath, "a key contains a line break"]);
+    }
+    while (pending.length > 0) {
+        const [value, field] = pending.pop();
+        if (typeof value === "string") {
+            if (hasLineBreakOrControl(value)) {
+                errors.push([field, "must not contain line breaks or control characters"]);
+            }
+        }
+        else if (Array.isArray(value)) {
+            for (const [index, item] of value.entries())
+                pending.push([item, `${field}[${index}]`]);
+        }
+        else if (value && typeof value === "object") {
+            for (const [key, item] of Object.entries(value)) {
+                if (hasLineBreakOrControl(key)) {
+                    errors.push([field, "a key contains a line break"]);
+                }
+                else {
+                    pending.push([item, `${field}.${key}`]);
+                }
+            }
+        }
+    }
+    return errors.sort(([a], [b]) => a.localeCompare(b));
+}
+const SERVICE_ROUTE_PATH_FIELDS = ["apiPath", "basePath"];
+export function getInvalidServiceRoutePathFields(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [];
+    const manifest = value;
+    return SERVICE_ROUTE_PATH_FIELDS.filter((field) => field in manifest && typeof manifest[field] !== "string");
+}
+export function validateServiceManifest(value, displayPath) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { errors: [`${displayPath}: expected a JSON object`], warnings: [] };
+    }
+    const manifest = value;
+    const errors = [];
+    for (const field of ["appName", "appType", "stack", "schemaVersion"]) {
+        if (!(field in manifest))
+            errors.push(`${displayPath}.${field}: required field is missing`);
+    }
+    for (const field of ["appName", "appType", "stack"]) {
+        if (field in manifest && typeof manifest[field] !== "string") {
+            errors.push(`${displayPath}.${field}: expected a string`);
+        }
+    }
+    if ("schemaVersion" in manifest && manifest.schemaVersion !== SERVICE_MANIFEST_SCHEMA_VERSION) {
+        errors.push(`${displayPath}.schemaVersion: unsupported version ${String(manifest.schemaVersion)} (supported: ${SERVICE_MANIFEST_SCHEMA_VERSION})`);
+    }
+    for (const field of getInvalidServiceRoutePathFields(manifest)) {
+        errors.push(`${displayPath}.${field}: expected a string`);
+    }
+    const dev = manifest.dev;
+    const liveReload = dev && typeof dev === "object" && !Array.isArray(dev)
+        ? dev.liveReload
+        : undefined;
+    if (liveReload !== undefined && typeof liveReload !== "boolean") {
+        errors.push(`${displayPath}.dev.liveReload: expected true or false`);
+    }
+    errors.push(...validateGeneratedStringFields(manifest, displayPath));
+    if ("smoke" in manifest) {
+        for (const message of validateSmoke(manifest.smoke))
+            errors.push(`${displayPath}.${message}`);
+    }
+    const warnings = Object.keys(manifest).flatMap((field) => {
+        const deprecation = DEPRECATED_FIELDS[field];
+        if (deprecation)
+            return [`${displayPath}.${field}: ${deprecation}`];
+        if (!KNOWN_SERVICE_FIELDS.has(field))
+            return [`${displayPath}.${field}: unknown field is preserved`];
+        return [];
+    });
+    if (liveReload === true && manifest.language !== "go") {
+        warnings.push(`${displayPath}.dev.liveReload: only applies to Go services (language "go"); it is ignored here`);
+    }
+    return { errors, warnings, manifest };
+}
+/**
+ * Generated-output errors for one service.json. A file that cannot be read or parsed returns none here, because
+ * validateServiceManifestFile reports that case.
+ */
+export function generatedFieldErrorsForFile(filePath, displayPath) {
+    if (!existsSync(filePath))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return [];
+        return validateGeneratedStringFields(parsed, displayPath);
+    }
+    catch {
+        return [];
+    }
+}
+export function validateServiceManifestFile(filePath, displayPath) {
+    if (!existsSync(filePath)) {
+        return { errors: [`${displayPath}: file is missing`], warnings: [] };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+        return validateServiceManifest(parsed, displayPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { errors: [`${displayPath}: invalid JSON (${message})`], warnings: [] };
+    }
+}

package/cli/dist/utils/service-runtime-state.js

@@ -0,0 +1,66 @@
+import { buildStartupReport, transitiveDependencies } from "./startup-report.js";
+import { effectiveRuntimeStatus, isTiltResourcePending } from "./tilt-resource-state.js";
+import { onlyEnabledResources } from "./up-readiness.js";
+/**
+ * The one answer to "is this service ready?" for `flisk status` and `flisk ui`, from Tilt's resources and the `dependsOn`
+ * in service.json. A service whose own process is up is still not ready while something it depends on has failed or
+ * is still starting. Services Tilt does not list are absent: the caller shows them as unknown.
+ */
+export function deriveServiceStates(jsonText, dependsOn, deferred = new Set()) {
+    const report = buildStartupReport(jsonText, dependsOn, deferred);
+    const failed = new Map(report.failed.map((entry) => [entry.name, entry.message]));
+    const blocked = new Map(report.blocked.map((entry) => [entry.name, entry.because]));
+    const starting = new Set(report.starting);
+    const items = JSON.parse(onlyEnabledResources(jsonText)).items ?? [];
+    const direct = new Map();
+    for (const item of items) {
+        const name = item.metadata?.name;
+        if (!name || name === "(Tiltfile)")
+            continue;
+        if (failed.has(name)) {
+            direct.set(name, { status: "error", reason: failed.get(name) });
+        }
+        else if (blocked.has(name)) {
+            const because = blocked.get(name) ?? [];
+            direct.set(name, {
+                status: "error",
+                reason: `${because.join(", ")} failed`,
+                blockedBy: because,
+            });
+        }
+        else if (starting.has(name)) {
+            direct.set(name, { status: "pending" });
+        }
+        else if (deferred.has(name) &&
+            isTiltResourcePending(item.status?.updateStatus ?? "", effectiveRuntimeStatus(item.status))) {
+            direct.set(name, { status: "unknown", reason: "starts on its first request" });
+        }
+        else {
+            direct.set(name, { status: "ready" });
+        }
+    }
+    const result = {};
+    for (const [name, state] of direct) {
+        if (state.status !== "ready") {
+            result[name] = state;
+            continue;
+        }
+        const deps = [...transitiveDependencies(name, dependsOn)].filter((dep) => direct.has(dep));
+        const failedDeps = deps.filter((dep) => direct.get(dep)?.status === "error").sort();
+        const waitingDeps = deps.filter((dep) => direct.get(dep)?.status === "pending").sort();
+        if (failedDeps.length > 0) {
+            result[name] = {
+                status: "error",
+                reason: `${failedDeps.join(", ")} failed`,
+                blockedBy: failedDeps,
+            };
+        }
+        else if (waitingDeps.length > 0) {
+            result[name] = { status: "pending", reason: `waiting for ${waitingDeps.join(", ")}` };
+        }
+        else {
+            result[name] = state;
+        }
+    }
+    return result;
+}