@flisk-sh/flisk 1.4.5 → 1.4.7

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/bun-requirement.js

@@ -1,10 +1,13 @@
+import { isNativeService } from "./native-service.js";
 import { isApiServiceType } from "./resource-kind.js";
 /**
  * Bun runs the generated JS services. A project without any has nothing for Bun to run, so neither `flisk doctor` nor
- * `flisk up` needs it. Doctor and the start-up preflight share this rule so they cannot disagree.
+ * `flisk up` needs it. A `command` service runs whatever its command names, so it never needs Bun on Flisk's behalf.
+ * Doctor and the start-up preflight share this rule so they cannot disagree.
  */
 export function projectNeedsBun(resources) {
-    return resources.some((resource) => isApiServiceType(resource.config?.appType) ||
-        resource.config?.appType === "frontend" ||
-        resource.config?.appType === "worker");
+    return resources.some((resource) => !isNativeService(resource) &&
+        (isApiServiceType(resource.config?.appType) ||
+            resource.config?.appType === "frontend" ||
+            resource.config?.appType === "worker"));
 }

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

@@ -11,9 +11,19 @@ import { checkColima } from "./colima.js";
 import { PROJECT_JSON } from "./constants.js";
 import { checkNatsBroker } from "./doctor-wiring.js";
 import { getHostPortPlan } from "./host-port-config.js";
+import { isNativeProject } from "./native-service.js";
 import { findProjectRoot } from "./paths.js";
 import { discoverResourcesFromRoot } from "./services.js";
 import { findOnPath } from "./which.js";
+/** Checks a project of `command` services needs: no container runtime, no Tilt, no gateway or database ports. */
+export const NATIVE_CHECK_IDS = ["node", "bun"];
+function blockingCheckIds(scope) {
+    if (scope === "scaffold")
+        return SCAFFOLD_CHECK_IDS;
+    if (scope === "native")
+        return NATIVE_CHECK_IDS;
+    return MACHINE_CHECK_IDS;
+}
 /** Checks that only the local runtime (starting a stack) needs. */
 export const RUNTIME_CHECK_IDS = ["docker", "compose", "tilt"];
 /** Checks that writing project configuration needs. */
@@ -71,11 +81,35 @@ export function usesPrisma(projectRoot) {
         return false;
     }
 }
+async function hostPortsItem(root, scope) {
+    try {
+        // Scaffolding must not talk to Docker at all, so the port plan is planned
+        // from the host ports alone.
+        const plan = await getHostPortPlan(root, scope === "scaffold" ? { inspectDocker: false } : {});
+        return {
+            id: "ports",
+            ok: true,
+            message: `HTTP ${plan.ingressHttp}, HTTPS ${plan.ingressHttps}, Postgres ${plan.postgres}`,
+        };
+    }
+    catch (error) {
+        return {
+            id: "ports",
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+            fix: "Set FLISK_HTTP_PORT, FLISK_HTTPS_PORT, or FLISK_POSTGRES_PORT to available host ports.",
+        };
+    }
+}
 export async function runColdPreflight(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
-    const scope = opts.scope ?? "runtime";
     const projectRoot = findProjectRoot(cwd);
     const inProject = Boolean(projectRoot);
+    const resources = projectRoot ? discoverResourcesFromRoot(projectRoot) : [];
+    // A project whose services all declare `command` runs them as local processes (#2231): Docker, Compose, Tilt, the
+    // gateway/database host ports and the container wiring checks do not apply, so they are not run or reported.
+    const isNative = isNativeProject(resources);
+    const scope = isNative ? "native" : (opts.scope ?? "runtime");
     const items = [];
     const nodeVersion = process.versions.node;
     items.push({
@@ -115,7 +149,7 @@ export async function runColdPreflight(opts = {}) {
         items.push(await safeCheck("tilt", checkTilt, "Tilt CLI not found"));
     }
     // Outside a project Bun stays required: `flisk project` is about to create services that need it.
-    const bunNeeded = projectRoot ? projectNeedsBun(discoverResourcesFromRoot(projectRoot)) : true;
+    const bunNeeded = projectRoot ? projectNeedsBun(resources) : true;
     let bun = false;
     const bunPath = bunNeeded ? findOnPath("bun") : undefined;
     if (bunPath) {
@@ -141,24 +175,9 @@ export async function runColdPreflight(opts = {}) {
             fix: bun ? undefined : "curl -fsSL https://bun.sh/install | bash",
         }
         : { id: "bun", ok: true, message: "Bun not needed: no generated JS services" });
-    try {
-        // Scaffolding must not talk to Docker at all, so the port plan is planned
-        // from the host ports alone.
-        const plan = await getHostPortPlan(projectRoot ?? cwd, scope === "scaffold" ? { inspectDocker: false } : {});
-        items.push({
-            id: "ports",
-            ok: true,
-            message: `HTTP ${plan.ingressHttp}, HTTPS ${plan.ingressHttps}, Postgres ${plan.postgres}`,
-        });
-    }
-    catch (error) {
-        items.push({
-            id: "ports",
-            ok: false,
-            message: error instanceof Error ? error.message : String(error),
-            fix: "Set FLISK_HTTP_PORT, FLISK_HTTPS_PORT, or FLISK_POSTGRES_PORT to available host ports.",
-        });
-    }
+    // The host port plan places the gateway and Postgres, which only the container runtime starts.
+    if (scope !== "native")
+        items.push(await hostPortsItem(projectRoot ?? cwd, scope));
     // Project wiring (NATS, Prisma database) describes a running stack, so it is
     // only probed for the runtime scope.
     if (projectRoot && scope === "runtime") {
@@ -198,18 +217,20 @@ export async function runColdPreflight(opts = {}) {
         }
     }
     const failures = items.filter((check) => !check.ok).slice(0, 8);
-    const blockingIds = scope === "scaffold" ? SCAFFOLD_CHECK_IDS : MACHINE_CHECK_IDS;
+    const blockingIds = blockingCheckIds(scope);
     const machineFailed = failures.some((check) => blockingIds.includes(check.id));
     const bunFailed = failures.some((check) => check.id === "bun");
     const header = failures.length
         ? machineFailed
-            ? scope === "scaffold"
-                ? bunFailed
-                    ? `Project setup blocked. Bun ${BUN_FLOOR_LABEL} must be installed on PATH.\nFix the machine checks below.`
-                    : "Project setup blocked. Fix the machine checks below."
-                : bunFailed
-                    ? `Cold start blocked. Bun ${BUN_FLOOR_LABEL} must be installed on PATH.\nPrisma/NATS configuration is project-specific and generated after \`flisk project\`. Fix the machine checks below.`
-                    : "Cold start blocked. Bun/Prisma/NATS are not the first failure.\nThey are generated after `flisk project`. Fix the machine checks below."
+            ? scope === "native"
+                ? "Cannot start the local processes. Fix the machine checks below."
+                : scope === "scaffold"
+                    ? bunFailed
+                        ? `Project setup blocked. Bun ${BUN_FLOOR_LABEL} must be installed on PATH.\nFix the machine checks below.`
+                        : "Project setup blocked. Fix the machine checks below."
+                    : bunFailed
+                        ? `Cold start blocked. Bun ${BUN_FLOOR_LABEL} must be installed on PATH.\nPrisma/NATS configuration is project-specific and generated after \`flisk project\`. Fix the machine checks below.`
+                        : "Cold start blocked. Bun/Prisma/NATS are not the first failure.\nThey are generated after `flisk project`. Fix the machine checks below."
             : "Machine is ready. Project wiring is not."
         : "";
     const footer = failures.length
@@ -217,7 +238,7 @@ export async function runColdPreflight(opts = {}) {
         : inProject
             ? "Environment ready for Flisk"
             : `This machine is ready for Flisk.\n${readyNextStep()}`;
-    return { ok: failures.length === 0, inProject, items: failures, header, footer };
+    return { ok: failures.length === 0, inProject, scope, items: failures, header, footer };
 }
 /** Formats only failed preflight checks and the applicable readiness message. */
 export function formatColdPreflight(result, options = {}) {
@@ -233,12 +254,14 @@ export function formatColdPreflight(result, options = {}) {
 }
 /** Exits before machine-dependent command work when any machine check fails. */
 export async function assertMachineReadyOrExit(opts = {}) {
-    const scope = opts.scope ?? "runtime";
-    const result = await runColdPreflight({ scope });
-    const blockingIds = scope === "scaffold" ? SCAFFOLD_CHECK_IDS : MACHINE_CHECK_IDS;
+    const result = await runColdPreflight({ scope: opts.scope });
+    const blockingIds = blockingCheckIds(result.scope);
     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-native.js

@@ -0,0 +1,96 @@
+import { formatCount } from "./formatting.js";
+import { findMissingPrograms, isPortListening, isProcessAlive, localUrl, planNativeRun, readNativeRunState, } from "./native-runtime.js";
+import { isNativeService } from "./native-service.js";
+import { findOnPath } from "./which.js";
+/**
+ * Doctor checks for a project whose services all declare `command` (#2231). Such a project runs as local processes, so doctor
+ * checks what those processes need (their programs, their dependsOn, their ports) instead of Docker, Compose and Tilt.
+ */
+/** Says which runtime doctor checked, so a missing Docker check reads as intended and not as forgotten. */
+export function checkNativeRuntime(resources) {
+    return {
+        name: "Runtime",
+        didPass: true,
+        message: `Local processes: ${formatCount(resources.length, "service")} declare a command, so Docker, Compose and Tilt are not needed`,
+    };
+}
+/** Each service's command starts a program that is installed. */
+export function checkNativeCommands(resources, find = findOnPath) {
+    const missing = findMissingPrograms(planNativeRun(resources.filter(isNativeService)).services, find);
+    if (missing.length === 0) {
+        return {
+            name: "Service commands",
+            didPass: true,
+            message: "Every service command starts a program that is installed",
+        };
+    }
+    return {
+        name: "Service commands",
+        didPass: false,
+        message: `${formatCount(missing.length, "service")} run a program that is not on PATH:\n    ${missing.map(({ name, program }) => `${name}: ${program}`).join("\n    ")}`,
+        fix: 'Install the program, or change "command" in the service.json',
+    };
+}
+/** A dependsOn name must be another service of the project: local processes cannot start a database or gateway for it. */
+export function checkNativeDependsOn(resources) {
+    const names = new Set(resources.map((resource) => resource.name));
+    const problems = resources.flatMap((resource) => {
+        const deps = resource.config?.dependsOn;
+        return (Array.isArray(deps) ? deps : [])
+            .filter((dep) => !names.has(dep))
+            .map((dep) => `${resource.name} dependsOn "${dep}", which is not a service of this project`);
+    });
+    if (problems.length === 0) {
+        return {
+            name: "Service dependencies",
+            didPass: true,
+            message: "Every dependsOn names a service of this project",
+        };
+    }
+    return {
+        name: "Service dependencies",
+        didPass: false,
+        message: problems.join("\n    "),
+        fix: "Add the missing service with a command, or remove it from dependsOn. A database or the gateway still needs the Docker path.",
+    };
+}
+/**
+ * When a native run is up, each service answers on its health URL (or accepts connections on its port). Skipped when nothing
+ * runs: doctor is also used before the first `flisk up`.
+ */
+export async function checkNativeServiceHealth(projectRoot, resources, timeoutMs) {
+    const state = readNativeRunState(projectRoot);
+    if (!state || !isProcessAlive(state.pid)) {
+        return {
+            name: "Service Health",
+            didPass: true,
+            isSkipped: true,
+            message: "Not running - start it with flisk up",
+        };
+    }
+    const failing = [];
+    for (const plan of planNativeRun(resources.filter(isNativeService)).services) {
+        if (plan.port === undefined)
+            continue;
+        const answered = plan.healthUrl
+            ? await fetch(plan.healthUrl, { signal: AbortSignal.timeout(timeoutMs) })
+                .then((response) => response.status < 400)
+                .catch(() => false)
+            : await isPortListening(plan.port, timeoutMs);
+        if (!answered)
+            failing.push(`${plan.name}: no answer from ${plan.healthUrl ?? localUrl(plan.port)}`);
+    }
+    if (failing.length === 0) {
+        return {
+            name: "Service Health",
+            didPass: true,
+            message: "Every running service answers",
+        };
+    }
+    return {
+        name: "Service Health",
+        didPass: false,
+        message: failing.join("\n    "),
+        fix: "Read the service output in .flisk/native/logs/<service>.log, or the flisk up terminal",
+    };
+}

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-project.js

@@ -0,0 +1,41 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { SERVICE_JSON } from "./constants.js";
+import { isNativeProject } from "./native-service.js";
+import { findProjectRoot } from "./paths.js";
+import { discoverResourcesWithProblems } from "./services.js";
+/** True when `dir` or a directory up to two levels below it has a service.json; a cheap test before a full discovery scan. */
+export function hasNearbyServiceJson(dir, depth = 0) {
+    if (existsSync(join(dir, SERVICE_JSON)))
+        return true;
+    if (depth >= 2)
+        return false;
+    try {
+        return readdirSync(dir, { withFileTypes: true }).some((entry) => entry.isDirectory() &&
+            !entry.name.startsWith(".") &&
+            entry.name !== "node_modules" &&
+            hasNearbyServiceJson(join(dir, entry.name), depth + 1));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The project a command for local processes works on: the Flisk project around `cwd`, or, before the first `flisk up` wrote
+ * .flisk/project.json, `cwd` itself when every service.json near it declares `command` (the directory `flisk up` adopts).
+ * Returns its services only when they all declare `command`; null otherwise, including outside any project.
+ */
+export function findNativeProject(cwd = process.cwd()) {
+    const projectRoot = findProjectRoot(cwd) ?? (hasNearbyServiceJson(cwd) ? cwd : null);
+    if (!projectRoot)
+        return null;
+    try {
+        const { resources } = discoverResourcesWithProblems(projectRoot);
+        return isNativeProject(resources) ? { projectRoot, resources } : null;
+    }
+    catch {
+        return null;
+    }
+}