@flisk-sh/flisk 1.4.6 → 1.4.7

package/cli/dist/utils/agent-format.js

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+/** "12s ago", "5m ago", "3h ago", "2d ago"; "-" when the agent sent no time. */
+export function formatAge(iso, now = Date.now()) {
+    if (!iso)
+        return "-";
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return iso;
+    const seconds = Math.max(0, Math.round((now - at) / 1000));
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m ago`;
+    if (seconds < 86_400)
+        return `${Math.floor(seconds / 3600)}h ago`;
+    return `${Math.floor(seconds / 86_400)}d ago`;
+}

package/cli/dist/utils/agent-sessions.js

@@ -0,0 +1,122 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import * as http from "node:http";
+export const AGENT_REQUEST_TIMEOUT_MS = 10_000;
+/** GET with node:http because fetch silently drops a custom Host header, which is what Traefik routes on. */
+export function httpGet(url, headers, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        // One signal covers the connection and the body read, so a hung agent cannot block the CLI.
+        const req = http.get(url, { headers, signal: AbortSignal.timeout(timeoutMs) }, (res) => {
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                const status = res.statusCode ?? 0;
+                resolve({
+                    ok: status >= 200 && status < 300,
+                    status,
+                    text: Buffer.concat(chunks).toString("utf-8"),
+                });
+            });
+            res.on("error", reject);
+        });
+        req.on("error", reject);
+    });
+}
+/**
+ * Agent containers publish no host port; the only way in is the Traefik route that `flisk status` prints as `url`
+ * (for example http://api.<project>.localhost:8080/api/bot). `*.localhost` does not resolve everywhere (glibc without
+ * systemd-resolved), so connect to loopback and keep the route's host in the Host header, which is all Traefik matches on.
+ */
+export function agentRequest(routeUrl, path, headers = {}) {
+    const route = new URL(routeUrl);
+    const allHeaders = { ...headers };
+    if (route.hostname.endsWith(".localhost")) {
+        allHeaders.host = route.host;
+        route.hostname = "127.0.0.1";
+    }
+    return { url: `${route.origin}${route.pathname.replace(/\/$/, "")}${path}`, headers: allHeaders };
+}
+/** The request for one session's checkpoint: `GET /session`, keyed by the `x-session-id` header. */
+export function agentSessionRequest(routeUrl, sessionId) {
+    return agentRequest(routeUrl, "/session", { "x-session-id": sessionId });
+}
+/** The request for the session list: `GET /sessions`, which needs no session id. */
+export function agentSessionListRequest(routeUrl) {
+    return agentRequest(routeUrl, "/sessions");
+}
+export async function fetchAgent(request, timeoutMs = AGENT_REQUEST_TIMEOUT_MS) {
+    let reply;
+    try {
+        reply = await httpGet(request.url, request.headers, timeoutMs);
+    }
+    catch {
+        return { kind: "not-running" };
+    }
+    let body = {};
+    let isJson = true;
+    try {
+        body = reply.text ? JSON.parse(reply.text) : {};
+    }
+    catch {
+        body = { raw: reply.text };
+        isJson = false;
+    }
+    if (reply.ok)
+        return { kind: "ok", body };
+    // Traefik answers 502/503/504 when the route has no live container and a plain-text 404 when it has no route at
+    // all. An agent's own errors are JSON, so a non-JSON 404 is the gateway, not the agent.
+    if ([502, 503, 504].includes(reply.status) || (reply.status === 404 && !isJson)) {
+        return { kind: "not-running" };
+    }
+    if (reply.status === 404)
+        return { kind: "not-found", body };
+    const detail = body?.error;
+    return {
+        kind: "error",
+        status: reply.status,
+        detail: typeof detail === "string" ? detail : reply.text,
+    };
+}
+/**
+ * Reads a `GET /sessions` body. Returns null when it is not the list shape, so a caller can tell a wrong endpoint from
+ * an agent with no sessions. Rows without a usable id are dropped; the agent owns its other fields.
+ */
+export function parseAgentSessionList(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const raw = body.sessions;
+    if (!Array.isArray(raw))
+        return null;
+    const sessions = [];
+    for (const row of raw) {
+        if (typeof row !== "object" || row === null)
+            continue;
+        const r = row;
+        if (typeof r.sessionId !== "string" || !r.sessionId)
+            continue;
+        sessions.push({
+            sessionId: r.sessionId,
+            lastActivity: typeof r.lastActivity === "string" ? r.lastActivity : null,
+            status: typeof r.status === "string" ? r.status : "unknown",
+            checkpointBytes: typeof r.checkpointBytes === "number" ? r.checkpointBytes : null,
+        });
+    }
+    const total = body.total;
+    return { sessions, total: typeof total === "number" ? total : sessions.length };
+}
+/** Reads `/ready` and `/sessions` once, in parallel. Never throws: a failure is part of the answer. */
+export async function fetchAgentOverview(routeUrl, timeoutMs = 3_000) {
+    const [ready, list] = await Promise.all([
+        fetchAgent(agentRequest(routeUrl, "/ready"), timeoutMs),
+        fetchAgent(agentRequest(routeUrl, "/sessions"), timeoutMs),
+    ]);
+    if (ready.kind === "not-running" && list.kind === "not-running")
+        return { state: "not-running" };
+    // /ready answers 503 with { ready: false } when the checkpoint store is down, which fetchAgent reports as "not-running".
+    const isReady = ready.kind === "ok" && ready.body?.ready === true;
+    return {
+        state: "up",
+        ready: isReady,
+        sessions: list.kind === "ok" ? parseAgentSessionList(list.body) : null,
+    };
+}

package/cli/dist/utils/agent-skills.js

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { loadTemplate } from "../generator/template-engine.js";
+// The agent skills `flisk project` writes into a new project, so a coding agent opened there knows how to build and run
+// the app with Flisk. Copies of .claude/skills/<name>/SKILL.md, shipped in cli/templates/agent-skills (a test keeps
+// them identical).
+export const PROJECT_AGENT_SKILLS = [
+    "flisk-build",
+    "flisk-recipe-starters",
+    "flisk-recipe-shop",
+    "flisk-recipe-saas",
+    "flisk-recipe-ai-agent",
+    "flisk-recipe-blog",
+    "flisk-doctor",
+    "flisk-up",
+    "flisk-resource",
+    "flisk-status",
+    "flisk-troubleshoot",
+    "flisk-agent-ops",
+];
+// Claude Code reads .claude/skills; Codex, Cursor and other agents read .agents/skills.
+export const AGENT_SKILL_DIRS = [".claude/skills", ".agents/skills"];
+const DOCS_URL = "https://github.com/flisk-sh/flisk/blob/main/docs/";
+export const PROJECT_AGENTS_MD = `# AGENTS.md
+
+This project runs on [Flisk](https://github.com/flisk-sh/flisk). To build or run something here, follow the Flisk skills in \`.agents/skills\` (Claude Code: \`.claude/skills\`), starting with \`flisk-build\`.
+
+- Add a service: \`flisk resource <name> --type <frontend|backend|worker|agent|mcp> --stack <stack> --yes\`
+- Start it: \`flisk up <stack>\`, then check every URL from \`flisk networks\`
+- When something fails: \`flisk doctor\`, then \`flisk logs -s <service>\`
+- Do not hand-write Dockerfiles, Compose files or Tiltfiles, and do not edit \`.autogenerated/\`: change \`service.json\` instead.
+`;
+// In the repository the skills link to docs/ with relative paths; in a user's project those point nowhere.
+export function rewriteSkillLinks(markdown) {
+    return markdown.replace(/\]\((?:\.\.\/)+docs\//g, `](${DOCS_URL}`);
+}
+/**
+ * Write the Flisk agent skills and an AGENTS.md into a project. Never overwrites: a file that already exists is left
+ * as it is, so a user's own edits survive `flisk project` running again. Returns the paths written, relative to the
+ * project root.
+ */
+export function installAgentSkills(projectRoot) {
+    const written = [];
+    for (const name of PROJECT_AGENT_SKILLS) {
+        const contents = rewriteSkillLinks(loadTemplate(`agent-skills/${name}/SKILL.md`));
+        for (const dir of AGENT_SKILL_DIRS) {
+            const rel = path.join(dir, name, "SKILL.md");
+            const target = path.join(projectRoot, rel);
+            if (existsSync(target))
+                continue;
+            mkdirSync(path.dirname(target), { recursive: true });
+            writeFileSync(target, contents);
+            written.push(rel);
+        }
+    }
+    const agentsMd = path.join(projectRoot, "AGENTS.md");
+    if (!existsSync(agentsMd)) {
+        writeFileSync(agentsMd, PROJECT_AGENTS_MD);
+        written.push("AGENTS.md");
+    }
+    return written;
+}

package/cli/dist/utils/cold-preflight.js

@@ -259,6 +259,9 @@ export async function assertMachineReadyOrExit(opts = {}) {
     const machineFailure = result.items.some((check) => blockingIds.includes(check.id));
     if (machineFailure) {
         console.error(formatColdPreflight(result));
+        // What to run once the machine checks pass; the caller knows its own next step.
+        for (const hint of opts.hints ?? [])
+            console.error(`→ ${hint}`);
         process.exit(1);
     }
 }

package/cli/dist/utils/doctor-fix-first.js

@@ -0,0 +1,93 @@
+import { CONTAINER_RUNTIME_CHECK } from "./constants.js";
+import { DISK_SPACE_CHECK } from "./doctor-host.js";
+const POSIX = (platform) => platform === "darwin" || platform === "linux";
+function conflictingPort(result) {
+    const match = /^\s*(\d{2,5}) \(/m.exec(result.message);
+    return match ? Number(match[1]) : null;
+}
+function inspectPort(platform, port) {
+    if (port === null)
+        return null;
+    if (platform === "darwin")
+        return `lsof -nP -iTCP:${port} -sTCP:LISTEN`;
+    if (platform === "linux")
+        return `ss -ltnp 'sport = :${port}'`;
+    return null;
+}
+const RULES = {
+    [CONTAINER_RUNTIME_CHECK]: {
+        tier: 0,
+        command: (platform) => platform === "darwin"
+            ? "open -a Docker"
+            : platform === "linux" && !process.env.WSL_DISTRO_NAME
+                ? "sudo systemctl start docker"
+                : null,
+    },
+    Colima: { tier: 1, command: (platform) => (POSIX(platform) ? "colima start" : null) },
+    "Host Ports": {
+        tier: 2,
+        command: (platform, result) => inspectPort(platform, conflictingPort(result)),
+    },
+    "Ingress Ports": { tier: 2, command: () => null },
+    "Tilt CLI": {
+        tier: 3,
+        command: (platform) => POSIX(platform)
+            ? "curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash"
+            : null,
+    },
+    Bun: {
+        tier: 3,
+        command: (platform) => (POSIX(platform) ? "curl -fsSL https://bun.sh/install | bash" : null),
+    },
+    "Docker Network Pool": { tier: 4, command: () => "flisk down --prune-networks" },
+    "Docker networks": { tier: 4, command: () => "flisk down --prune-networks" },
+    [DISK_SPACE_CHECK]: { tier: 5, command: () => "docker system prune -af" },
+    "Flisk installs": { tier: 6, command: () => "flisk upgrade" },
+    "Flisk version": { tier: 6, command: () => "flisk upgrade" },
+    "Master Configs": { tier: 7, command: () => "flisk project" },
+    "Generated Runtime Assets": { tier: 7, command: () => "flisk config regenerate" },
+    "Starlark Load Exports": { tier: 7, command: () => "flisk config regenerate" },
+};
+/** Project-level findings come after every machine-level one that has no rule. */
+const UNRANKED_TIER = 99;
+export function checkId(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Failing checks ordered by how much they block, each with one runnable command. Hard failures come before
+ * warnings (a low-disk warning never outranks a stopped daemon), and a port 5432 conflict leads the port tier.
+ * Checks without a command that is valid on this platform are left out; their prose fix is still printed.
+ */
+export function rankDoctorFixes(results, platform = process.platform) {
+    const candidates = results
+        .filter((result) => !result.didPass && !result.isSkipped)
+        .map((result, index) => {
+        const rule = RULES[result.name];
+        return {
+            result,
+            index,
+            tier: rule?.tier ?? UNRANKED_TIER,
+            command: rule?.command(platform, result) ?? null,
+        };
+    })
+        .filter((entry) => entry.command !== null);
+    const weight = (entry) => (entry.result.isWarning ? 1000 : 0) +
+        entry.tier * 10 +
+        (entry.result.name === "Host Ports" && conflictingPort(entry.result) === 5432 ? 0 : 1);
+    candidates.sort((left, right) => weight(left) - weight(right) || left.index - right.index);
+    return candidates.map((entry, position) => ({
+        rank: position + 1,
+        checkId: checkId(entry.result.name),
+        check: entry.result.name,
+        command: entry.command,
+    }));
+}
+/** The human "Fix first" section, or an empty list when there is nothing to run. */
+export function formatFixFirst(fixes) {
+    if (fixes.length === 0)
+        return [];
+    return fixes.flatMap((fix) => [`  ${fix.rank}. ${fix.check}`, `     ${fix.command}`]);
+}

package/cli/dist/utils/doctor-report.js

@@ -1,4 +1,5 @@
 import { CONTAINER_RUNTIME_CHECK } from "./constants.js";
+import { rankDoctorFixes } from "./doctor-fix-first.js";
 import { SCHEMA_VERSION } from "./machine-output.js";
 /** Wait for concurrent probes to finish even if one throws, so they can release resources. */
 export async function collectDoctorChecks(machineChecks, projectChecks) {
@@ -28,6 +29,7 @@ function containerRuntimeReachable(checks) {
 }
 /** Produce the same readiness decision for human and machine consumers. */
 export function createDoctorReport(checks, inProject, errors = [], portPlan, host) {
+    const fixFirst = rankDoctorFixes(checks);
     return {
         schemaVersion: SCHEMA_VERSION,
         data: {
@@ -35,6 +37,7 @@ export function createDoctorReport(checks, inProject, errors = [], portPlan, hos
                 checks.every((check) => check.didPass || check.isSkipped || check.isWarning),
             inProject,
             checks,
+            ...(fixFirst.length > 0 ? { fixFirst } : {}),
             ...(host
                 ? {
                     host: {

package/cli/dist/utils/native-runtime.js

@@ -406,6 +406,9 @@ export class NativeSupervisor {
     spawn(service) {
         const { plan } = service;
         service.startedAt = Date.now();
+        // `command` is a shell command line the project owner wrote in their own service.json (`PORT=1 node s.js`, `$PORT`,
+        // `a && b`), run with the same trust as an npm script or a Procfile entry; nothing from outside the project reaches it.
+        // nosemgrep: javascript.lang.security.audit.spawn-shell-true.spawn-shell-true
         const child = spawn(plan.command, {
             cwd: plan.cwd,
             env: { ...(this.options.baseEnv ?? process.env), ...plan.env },

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

@@ -3,7 +3,7 @@
  * `command` runs as a local process started by `flisk up`, with no image, no Dockerfile and no generated files.
  *
  * ```json
- * { "name": "api", "command": "node server.js", "port": 4000, "env": { "GREETING": "hi" }, "dependsOn": [], "healthCheckPath": "/health" }
+ * { "appName": "api", "appType": "backend", "command": "node server.js", "port": 4000, "env": { "GREETING": "hi" }, "dependsOn": [] }
  * ```
  *
  * `dev.command` is a different field: it is the dev command inside a generated container (see the Python example) and does not
@@ -54,7 +54,7 @@ export function validateNativeServiceFields(manifest) {
     return errors;
 }
 function serviceLabel(manifest) {
-    const name = typeof manifest.appName === "string" ? manifest.appName : manifest.name;
+    const name = manifest.appName;
     return typeof name === "string" && name ? `"${name}"` : "(unnamed)";
 }
 /**

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

@@ -186,21 +186,14 @@ export function validateServiceManifest(value, displayPath) {
     }
     const manifest = value;
     const errors = [];
-    // A `command` service needs only a name and schemaVersion: it runs as a local process, so it has no app type, stack or
-    // generated output to describe (the minimal contract in utils/native-service.ts). Every other service keeps the full set.
-    if (declaresCommand(manifest)) {
-        if (!("appName" in manifest) && typeof manifest.name !== "string") {
-            errors.push(`${displayPath}.name: required field is missing`);
-        }
-        if (!("schemaVersion" in manifest)) {
-            errors.push(`${displayPath}.schemaVersion: required field is missing`);
-        }
-    }
-    else {
-        for (const field of ["appName", "appType", "stack", "schemaVersion"]) {
-            if (!(field in manifest))
-                errors.push(`${displayPath}.${field}: required field is missing`);
-        }
+    // A `command` service runs as a local process, so it has no stack to group generated output by (the minimal contract in
+    // utils/native-service.ts). Every other service keeps the full set.
+    const requiredFields = declaresCommand(manifest)
+        ? ["appName", "appType", "schemaVersion"]
+        : ["appName", "appType", "stack", "schemaVersion"];
+    for (const field of requiredFields) {
+        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") {

package/cli/dist/utils/services.js

@@ -3,7 +3,7 @@
 import fs, { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { Cache, createCacheValidator } from "./cache.js";
-import { AUTOGENERATED_FILE_PATTERNS, BRING_YOUR_OWN_TYPE, DOCKER_COMPOSE_FILE, PACKAGE_JSON, SERVICE_JSON, SKIP_DIRECTORIES, } from "./constants.js";
+import { AUTOGENERATED_FILE_PATTERNS, DOCKER_COMPOSE_FILE, PACKAGE_JSON, SERVICE_JSON, SKIP_DIRECTORIES, } from "./constants.js";
 import { errorFactories } from "./errors.js";
 import { formatCount } from "./formatting.js";
 import { declaresCommand, validateNativeServiceFields } from "./native-service.js";
@@ -41,9 +41,9 @@ function isValidResourceConfig(value) {
     if (!value || typeof value !== "object")
         return false;
     const config = value;
-    // A `command` service (the minimal contract) needs only a name, as appName or name.
+    // A `command` service (the minimal contract) has no legacy forms: appName and appType.
     if (declaresCommand(config)) {
-        return typeof config.appName === "string" || typeof config.name === "string";
+        return typeof config.appName === "string" && typeof config.appType === "string";
     }
     // Accept runtime, appType, or type (for backward compatibility with existing service.json files)
     const hasRuntimeOrAppType = typeof config.runtime === "string" ||
@@ -84,7 +84,9 @@ function parseResource(serviceJsonPath) {
         throw new InvalidServiceJsonError(`invalid JSON: ${errorMessage(error)}`);
     }
     if (!isValidResourceConfig(parsed)) {
-        throw new InvalidServiceJsonError("missing required fields (appName, runtime or appType)");
+        throw new InvalidServiceJsonError(declaresCommand(parsed)
+            ? "missing required fields (appName and appType)"
+            : "missing required fields (appName, runtime or appType)");
     }
     const nativeErrors = validateNativeServiceFields(parsed);
     if (nativeErrors.length > 0)
@@ -106,13 +108,8 @@ function parseResource(serviceJsonPath) {
     }
     const config = {
         ...parsedConfig,
-        appName: parsedConfig.appName ?? String(parsedConfig.name),
-        // A `command` service without a type is the user's own program, like a bring-your-own container.
         appType: (parsedConfig.appType ||
-            parsedConfig.type ||
-            (declaresCommand(parsedConfig)
-                ? BRING_YOUR_OWN_TYPE
-                : undefined)),
+            parsedConfig.type),
     };
     const resourceDir = dirname(serviceJsonPath);
     return {

package/cli/dist/utils/startup-report.js

@@ -4,6 +4,35 @@ import { parseTiltResourceFailures, summarizeTiltBuildError } from "./doctor-run
 import { conflictPort, portConflictFix } from "./port-conflict-fix.js";
 import { effectiveRuntimeStatus, isTiltResourcePending } from "./tilt-resource-state.js";
 import { onlyEnabledResources } from "./up-readiness.js";
+/** The resources Tilt says this one is waiting for. */
+function waitingOn(item) {
+    return (item.status?.waiting?.on ?? [])
+        .filter((ref) => (ref.kind ?? "UIResource") === "UIResource" && ref.name)
+        .map((ref) => ref.name);
+}
+// Docker has no free subnet left for a new network (every project creates several and `flisk down` keeps them).
+const NETWORK_POOL_EXHAUSTED = /all predefined address pools have been fully subnetted/i;
+/**
+ * Tilt's error for a failed local command is only "exit status 1"; the reason (for example Docker's "all predefined
+ * address pools have been fully subnetted") is in the resource's log. Returns the fix for each failed resource whose
+ * message or log names a known machine problem.
+ */
+export async function machineProblemFixes(failures, fetchLogs) {
+    const fixes = new Map();
+    for (const { name, message } of failures.slice(0, 5)) {
+        const fix = machineProblemFix(message) ?? machineProblemFix((await fetchLogs(name)) ?? "");
+        if (fix)
+            fixes.set(name, fix);
+    }
+    return fixes;
+}
+/** A plain fix for a failure message that names a known machine problem, or null. */
+export function machineProblemFix(message) {
+    if (NETWORK_POOL_EXHAUSTED.test(message)) {
+        return "Fix: Docker has no free network ranges left. Run `flisk down --prune-networks` in Flisk projects you no longer use (or `docker network prune` to remove every unused network), then run flisk up again";
+    }
+    return null;
+}
 export function transitiveDependencies(name, dependsOn) {
     const seen = new Set();
     const visit = (current) => {
@@ -31,13 +60,24 @@ export function buildStartupReport(jsonText, dependsOn, deferred = new Set()) {
     }));
     const failedNames = new Set(failed.map((entry) => entry.name));
     const items = JSON.parse(enabledJson).items ?? [];
+    // service.json dependsOn, plus what Tilt reports as waited for (shared infrastructure such as init-networks, which no
+    // service.json names).
+    const deps = { ...dependsOn };
+    for (const item of items) {
+        const name = item.metadata?.name;
+        if (!name)
+            continue;
+        const waits = waitingOn(item);
+        if (waits.length > 0)
+            deps[name] = [...new Set([...(deps[name] ?? []), ...waits])];
+    }
     const blocked = [];
     const starting = [];
     for (const item of items) {
         const name = item.metadata?.name ?? "unknown";
         if (name === "(Tiltfile)" || failedNames.has(name) || deferred.has(name))
             continue;
-        const because = [...transitiveDependencies(name, dependsOn)]
+        const because = [...transitiveDependencies(name, deps)]
             .filter((dep) => failedNames.has(dep))
             .sort();
         if (because.length > 0)
@@ -52,12 +92,14 @@ export function isStartupStalled(jsonText, dependsOn, deferred = new Set()) {
     const report = buildStartupReport(jsonText, dependsOn, deferred);
     return report.failed.length > 0 && report.starting.length === 0;
 }
-export function formatStartupReport(report, timedOut, occupantOf) {
+export function formatStartupReport(report, timedOut, occupantOf, machineFixes = new Map()) {
     const lines = [];
     for (const { name, message } of report.failed) {
         lines.push(`✗ ${name} failed: ${message}`);
         const port = conflictPort(message);
-        const fix = portConflictFix(message, port !== null && occupantOf ? occupantOf(port) : null);
+        const fix = portConflictFix(message, port !== null && occupantOf ? occupantOf(port) : null) ??
+            machineFixes.get(name) ??
+            machineProblemFix(message);
         if (fix)
             lines.push(`  ${fix}`);
     }

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

@@ -0,0 +1,23 @@
+/** Label of the group that holds services declared without a stack. */
+export const NO_STACK_LABEL = "(no stack)";
+/** A service that is failing or still starting. Unknown (not running, starts on request) is neither. */
+export function isUnhealthyState(state) {
+    return state?.status === "error" || state?.status === "pending";
+}
+/** Services grouped by stack, then the ones without a stack, each with its healthy/total count. */
+export function groupServicesByStack(stacks, unassigned, states) {
+    const build = (name, resources) => ({
+        name,
+        resources: [...resources],
+        healthy: resources.filter((resource) => states?.[resource.name]?.status === "ready").length,
+        total: resources.length,
+    });
+    const groups = stacks.map((stack) => build(stack.name, stack.resources));
+    if (unassigned.length > 0)
+        groups.push(build(NO_STACK_LABEL, unassigned));
+    return groups;
+}
+/** Names of the failing or pending services, in discovery order. */
+export function unhealthyServiceNames(resources, states) {
+    return resources.filter((r) => isUnhealthyState(states?.[r.name])).map((r) => r.name);
+}

package/cli/dist/utils/up-hints.js

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+const DOCS = "https://github.com/flisk-sh/flisk/blob/main/docs";
+/** Troubleshooting entries the hints point at. Each anchor is a heading in docs/troubleshooting.md. */
+export const UP_HINT_DOCS = {
+    coldStart: `${DOCS}/troubleshooting.md#cold-start-blocked-docker-or-tilt-missing`,
+    unhealthy: `${DOCS}/troubleshooting.md#services-never-turn-healthy-or-are-left-behind`,
+    smoke: `${DOCS}/smoke.md`,
+};
+/**
+ * One or two commands to run next after a failed `flisk up`, plus the troubleshooting page for that failure. Printed
+ * under the error and, with `--json`, carried in the error's `suggestions` field.
+ */
+export function upFailureHints(failure) {
+    switch (failure.kind) {
+        case "machine":
+            return [
+                "Fix the checks above, then run: flisk doctor",
+                `Troubleshooting: ${UP_HINT_DOCS.coldStart}`,
+            ];
+        case "invalid-tilt-port":
+            return ["Unset it to use the default port: unset TILT_PORT"];
+        case "tilt-exited":
+            return [
+                "Check Docker, Tilt and the project: flisk doctor",
+                "Rerun with Tilt's own output: flisk up --verbose",
+            ];
+        case "services":
+        case "smoke": {
+            const logs = failure.failed.length > 0
+                ? [`See why ${failure.failed[0]} failed: flisk logs -s ${failure.failed[0]}`]
+                : [];
+            return failure.kind === "smoke"
+                ? [...logs, `Smoke checks: ${UP_HINT_DOCS.smoke}`]
+                : [
+                    ...logs,
+                    "Check the whole stack: flisk doctor",
+                    `Troubleshooting: ${UP_HINT_DOCS.unhealthy}`,
+                ];
+        }
+    }
+}