@flisk-sh/flisk 1.4.2 → 1.4.6

package/cli/dist/commands/doctor.js

@@ -15,6 +15,7 @@ import { isPathDiscovered, readDiscoveryPaths } from "../utils/discovery-paths.j
 import { checkCrashLoopingContainers } from "../utils/doctor-crashloop.js";
 import { applyDoctorFixes, checkDuplicateFliskInstalls, hasFailedActions, planDoctorFixes, projectTiltPids, } from "../utils/doctor-fix.js";
 import { checkDiskSpace, dockerDesktopStuck } from "../utils/doctor-host.js";
+import { checkNativeCommands, checkNativeDependsOn, checkNativeRuntime, checkNativeServiceHealth, } from "../utils/doctor-native.js";
 import { collectDoctorChecks, createDoctorReport, getDoctorExitCode, } from "../utils/doctor-report.js";
 import { checkHealthRoutes, checkIngressPorts, checkPrivateNpmRegistry, checkTiltResourceHealth, projectConfigEnablesVerdaccio, summarizeAdvertisedProbes, summarizeServiceProbes, summarizeSmokeResults, } from "../utils/doctor-runtime.js";
 import { checkStarlarkLoadExports } from "../utils/doctor-starlark.js";
@@ -25,6 +26,7 @@ import { evaluateFliskVersionFloor } from "../utils/flisk-version.js";
 import { formatCount } from "../utils/formatting.js";
 import { getHostPortPlan, resolveRuntimeIngressPort } from "../utils/host-port-config.js";
 import { createHostPortPlan } from "../utils/host-port-plan.js";
+import { findNativeProject } from "../utils/native-project.js";
 import { findProjectRoot, getPackageVersion } from "../utils/paths.js";
 import { promptConfirm } from "../utils/prompt.js";
 import { EnvUnreadableError, envSecretValues, redactSecrets, redactValue, } from "../utils/secret-redaction.js";
@@ -291,7 +293,8 @@ export async function checkColima() {
         name: "Colima",
         didPass: false,
         message: status.problem ?? "The Colima VM is not running",
-        fix: status.fix,
+        fix: status.fix ??
+            "Start Colima: colima start\n  Verify: colima status\n  Docs: https://github.com/abiosoft/colima",
     };
 }
 export async function checkDockerRuntime() {
@@ -309,7 +312,7 @@ export async function checkDockerRuntime() {
                 name: CONTAINER_RUNTIME_CHECK,
                 didPass: false,
                 message: "Docker is not running",
-                fix: DOCTOR_FIXES.dockerDaemonDown,
+                fix: "Start Docker Desktop, enable WSL2 integration, then retry: flisk doctor\n  Verify: docker ps\n  Docs: https://docs.docker.com/desktop/wsl/",
             };
         }
     }
@@ -327,8 +330,8 @@ export async function checkDockerRuntime() {
             return {
                 name: CONTAINER_RUNTIME_CHECK,
                 didPass: false,
-                message: "Docker daemon is not responding",
-                fix: DOCTOR_FIXES.dockerDaemonDown,
+                message: "Docker daemon is not responding (timeout)",
+                fix: "Restart Docker daemon: systemctl restart docker (Linux) or restart Docker Desktop/Colima\n  Verify: docker ps\n  Docs: https://docs.docker.com/config/daemon/",
             };
         }
     }
@@ -349,7 +352,7 @@ export async function checkDockerRuntime() {
             name: CONTAINER_RUNTIME_CHECK,
             didPass: false,
             message: "Colima is installed but not running",
-            fix: DOCTOR_FIXES.dockerDaemonDown,
+            fix: "Start Colima: colima start\n  Verify: colima status\n  Docs: https://github.com/abiosoft/colima",
         };
     }
     if (await succeeds("podman ps")) {
@@ -364,14 +367,14 @@ export async function checkDockerRuntime() {
             name: CONTAINER_RUNTIME_CHECK,
             didPass: false,
             message: "Docker daemon is not running",
-            fix: DOCTOR_FIXES.dockerDaemonDown,
+            fix: "Start Docker daemon: systemctl start docker (Linux) or start Docker Desktop\n  Verify: docker ps\n  Docs: https://docs.docker.com/engine/daemon/",
         };
     }
     return {
         name: CONTAINER_RUNTIME_CHECK,
         didPass: false,
-        message: "Docker is not running",
-        fix: DOCTOR_FIXES.dockerMissing,
+        message: "Docker is not installed",
+        fix: "Install Docker: https://docs.docker.com/get-docker/\n  Verify: docker --version\n  After install, start Docker and retry: flisk doctor",
     };
 }
 export const checkDockerCompose = createExecCheck("Docker Compose", "docker compose version", "Docker Compose plugin available", "Docker Compose plugin not found", "Install Docker Compose: https://docs.docker.com/compose/install/");
@@ -442,7 +445,7 @@ export async function checkDockerVersions(exec = execAsync) {
         name: "Docker Versions",
         didPass: false,
         message: `Docker is too old for generated healthchecks (they use start_interval):\n    ${problems.join("\n    ")}`,
-        fix: "Update Docker Desktop, or on Linux update docker-ce and the docker-compose-plugin package",
+        fix: "Update Docker: Docker Desktop (auto-updates), or Linux: apt/yum/dnf update docker-ce docker-compose-plugin\n  Verify: docker version --format '{{.Server.Version}}' && docker compose version --short\n  Docs: https://docs.docker.com/engine/install/",
     };
 }
 checkDockerVersions.requiresContainerRuntime = true;
@@ -457,7 +460,7 @@ export async function checkTilt(exec = execAsync) {
             name: "Tilt CLI",
             didPass: false,
             message: "Tilt CLI not found",
-            fix: DOCTOR_FIXES.tiltMissing,
+            fix: "Install Tilt: curl -fsSL https://raw.githubusercontent.com/tilt-dev/tilt/master/scripts/install.sh | bash\n  Verify: tilt version\n  Docs: https://docs.tilt.dev/install.html",
         };
     }
     if (!versionMeetsMinimum(raw, MIN_TILT_VERSION)) {
@@ -465,7 +468,7 @@ export async function checkTilt(exec = execAsync) {
             name: "Tilt CLI",
             didPass: false,
             message: `Tilt ${raw || "version unknown"} is below the required v${MIN_TILT_VERSION.join(".")} floor`,
-            fix: `Install Tilt v${MIN_TILT_VERSION.join(".")} or newer: https://docs.tilt.dev/install.html`,
+            fix: `Upgrade Tilt to v${MIN_TILT_VERSION.join(".")} or newer: https://docs.tilt.dev/install.html\n  Verify: tilt version\n  If using Homebrew: brew upgrade tilt`,
         };
     }
     return { name: "Tilt CLI", didPass: true, message: `Tilt ${raw} is available` };
@@ -490,7 +493,7 @@ export async function checkDockerOperatingSystem(exec = execAsync) {
             name: "Docker OS",
             didPass: false,
             message: `Docker is using the ${osType || "unknown"} engine; Flisk requires Linux containers`,
-            fix: "Switch Docker Desktop to Linux containers, enable WSL2 integration, then retry flisk doctor.",
+            fix: "Switch Docker Desktop to Linux containers: Settings > General > Use the WSL 2 based engine\n  Or on Windows: docker context use default (if using WSL2 backend)\n  Verify: docker info --format '{{.OSType}}'\n  Docs: https://docs.docker.com/desktop/wsl/",
         };
     }
     return { name: "Docker OS", didPass: true, message: "Docker is using Linux containers" };
@@ -522,7 +525,7 @@ export async function checkBun(exec = execAsync) {
                 name: "Bun",
                 didPass: false,
                 message: `Bun ${rawVersion || "version unknown"} is below the required ${MIN_BUN_VERSION.join(".")} floor`,
-                fix: `Install Bun ${MIN_BUN_VERSION.join(".")} or newer: https://bun.sh/install`,
+                fix: `Upgrade Bun to ${MIN_BUN_VERSION.join(".")} or newer: https://bun.sh/install\n  Verify: bun --version\n  If using npm: npm install -g bun@latest`,
             };
         }
         return {
@@ -535,8 +538,8 @@ export async function checkBun(exec = execAsync) {
         return {
             name: "Bun",
             didPass: false,
-            message: "Bun is not available",
-            fix: DOCTOR_FIXES.bunMissing,
+            message: "Bun is not installed",
+            fix: "Install Bun: curl -fsSL https://bun.sh/install | bash\n  Verify: bun --version\n  Docs: https://bun.sh/docs/installation",
         };
     }
 }
@@ -1284,8 +1287,13 @@ export const doctorCommand = new Command("doctor")
         process.exit(2);
         return;
     }
+    // A project whose services all declare `command` runs as local processes: doctor checks only what they need (#2231).
+    const nativeProject = findNativeProject();
+    const nativeResources = nativeProject?.resources ?? null;
     if (!options.json) {
-        console.log("Flisk doctor checks your local Docker + Tilt development environment; it does not check cluster deployments.");
+        console.log(nativeResources
+            ? "Flisk doctor checks what this project's local processes need; its services declare commands, so Docker and Tilt are not checked."
+            : "Flisk doctor checks your local Docker + Tilt development environment; it does not check cluster deployments.");
     }
     const host = detectHost();
     if (process.platform === "win32") {
@@ -1342,10 +1350,15 @@ export const doctorCommand = new Command("doctor")
         console.log(`\n${chalk.bold("🔍 Flisk Doctor")}\n`);
         console.log("Checking environment...\n");
     }
-    const projectRoot = findProjectRoot();
+    // A directory of command services is a project for doctor even before `flisk up` writes its .flisk/project.json.
+    const projectRoot = findProjectRoot() ?? nativeProject?.projectRoot ?? null;
     // Repairs run before the checks so the checks report the state after the fix.
     let fixActions;
-    if (options.fix) {
+    if (options.fix && nativeResources) {
+        // The repairs are for Docker networks and Tilt probes, which a project of local processes does not have.
+        fixActions = [];
+    }
+    else if (options.fix) {
         try {
             let projectName;
             if (projectRoot) {
@@ -1387,16 +1400,19 @@ export const doctorCommand = new Command("doctor")
         if (!options.json)
             printFixActions(fixActions, options.dryRun);
     }
+    // The host port plan places the gateway and Postgres containers; a project of local processes has neither.
     let hostPortPlan;
     let portPlanError;
-    try {
-        hostPortPlan = await getHostPortPlan(projectRoot ?? process.cwd());
-    }
-    catch (error) {
-        hostPortPlan = null;
-        portPlanError = error instanceof Error ? error.message : String(error);
+    if (!nativeResources) {
+        try {
+            hostPortPlan = await getHostPortPlan(projectRoot ?? process.cwd());
+        }
+        catch (error) {
+            hostPortPlan = null;
+            portPlanError = error instanceof Error ? error.message : String(error);
+        }
     }
-    const machineChecks = [
+    const containerMachineChecks = [
         () => hostPortPlan
             ? {
                 name: "Host Ports",
@@ -1433,7 +1449,7 @@ export const doctorCommand = new Command("doctor")
         requiresContainerRuntime("Docker Network Pool", () => checkDockerNetworkCapacity()),
         () => checkDuplicateFliskInstalls(),
     ];
-    const projectChecks = [
+    const containerProjectChecks = [
         () => checkFliskVersion(),
         checkMasterConfigs,
         checkGeneratedProjectRuntimeAssets,
@@ -1494,8 +1510,31 @@ export const doctorCommand = new Command("doctor")
         // When Tilt is up, surface red resources (Traefik/apps never started).
         requiresContainerRuntime("Tilt Resources", checkTiltResourceHealth),
     ];
+    const machineChecks = nativeResources
+        ? [
+            () => checkNativeRuntime(nativeResources),
+            () => checkNativeCommands(nativeResources),
+            () => checkWslProjectLocation(findProjectRoot() ?? process.cwd(), options.strict),
+            () => checkDuplicateFliskInstalls(),
+        ]
+        : containerMachineChecks;
+    const projectChecks = nativeResources
+        ? [
+            () => checkFliskVersion(),
+            () => checkDuplicateResourceNames(),
+            () => checkDependsOnShape(),
+            () => checkNativeDependsOn(nativeResources),
+            () => checkCircularDependencies(),
+            () => checkServicePorts(),
+            () => checkSchemaVersions(undefined, options.strict),
+            () => checkDuplicateResourcePorts(),
+        ]
+        : containerProjectChecks;
+    if (options.ping && nativeResources && projectRoot) {
+        projectChecks.push(() => checkNativeServiceHealth(projectRoot, nativeResources, pingTimeout));
+    }
     // Runs last: needs routable services (and working Traefik) to mean anything.
-    if (options.ping) {
+    if (options.ping && !nativeResources) {
         // Probe the port a running stack is actually on, not the one the next `flisk up` would pick.
         const pingPort = projectRoot
             ? resolveRuntimeIngressPort(projectRoot, hostPortPlan?.ingressHttp)

package/cli/dist/commands/down.js

@@ -8,8 +8,10 @@ import { pruneProjectNetworks, stopProjectTiltUp, waitForTiltUpExit, } from "../
 import { errorFactories, handleTiltFailure, withTiltCheck } from "../utils/errors.js";
 import { createJsonEmitter } from "../utils/json-output.js";
 import { writeMachineError } from "../utils/machine-output.js";
+import { readNativeRunState, stopNativeRun } from "../utils/native-runtime.js";
+import { isNativeProject } from "../utils/native-service.js";
 import { findProjectRoot } from "../utils/paths.js";
-import { discoverResources, discoverStacks } from "../utils/services.js";
+import { discoverResources, discoverResourcesFromRoot, discoverStacks } from "../utils/services.js";
 import { buildTiltDownArgs, getTiltfilePath, runTilt } from "../utils/tilt.js";
 function allStackNames() {
     try {
@@ -20,6 +22,17 @@ function allStackNames() {
         return undefined;
     }
 }
+/** True when `flisk down` stops local processes instead of Tilt: a native run is on record, or every service declares `command`. */
+function isNativeRun(projectRoot) {
+    if (readNativeRunState(projectRoot))
+        return true;
+    try {
+        return isNativeProject(discoverResourcesFromRoot(projectRoot));
+    }
+    catch {
+        return false;
+    }
+}
 function pruneNetworksOrWarn(json) {
     const root = findProjectRoot();
     if (!root)
@@ -64,6 +77,25 @@ export const downCommand = addYesOption(new Command("down"))
         }
     }
     const emit = options.json ? createJsonEmitter("DOWN_FAILED", "flisk down") : undefined;
+    // A project of `command` services (or one with a native run on record) stops without Docker or Tilt.
+    const projectRoot = findProjectRoot();
+    if (isNativeRun(projectRoot)) {
+        if (emit && options.dryRun) {
+            emit({ ok: true, dryRun: true, runtime: "native" });
+            return;
+        }
+        if (handleDryRun(options, "not stopping local processes", "stop the local processes of this project")) {
+            return;
+        }
+        const stopped = await stopNativeRun(projectRoot);
+        if (!options.json) {
+            console.log(stopped.wasRunning
+                ? chalk.blue(`Stopped local processes: ${stopped.services.join(", ")}`)
+                : chalk.gray("Nothing is running for this project."));
+        }
+        emit?.({ ok: true, runtime: "native", stopped: stopped.services });
+        return;
+    }
     await withTiltCheck(async () => {
         if (emit && options.dryRun) {
             emit({ ok: true, dryRun: true });

package/cli/dist/commands/logs.js

@@ -4,10 +4,13 @@ import { Command } from "commander";
 import { STANDARD_PORTS } from "../utils/constants.js";
 import { errorFactories, FliskError, runCommand, showErrorAndExit } from "../utils/errors.js";
 import { createMachineEnvelope } from "../utils/machine-output.js";
+import { readNativeLogLines } from "../utils/native-runtime.js";
+import { isNativeProject } from "../utils/native-service.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { EnvUnreadableError, envSecretValues, redactSecrets, redactValue, } from "../utils/secret-redaction.js";
+import { discoverResourcesFromRoot } from "../utils/services.js";
 import { isTiltAvailable, runTilt } from "../utils/tilt.js";
-import { DEFAULT_LOG_TAIL, isTiltConnectionFailure, isValidPort, isValidSince, isValidTail, MAX_LOG_TAIL, parseTiltLogLines, } from "../utils/tilt-logs.js";
+import { DEFAULT_LOG_TAIL, isTiltConnectionFailure, isValidPort, isValidSince, isValidTail, MAX_LOG_TAIL, parseTiltLogLines, sinceMilliseconds, } from "../utils/tilt-logs.js";
 import { tiltUnreachableMessage } from "../utils/tilt-unreachable-message.js";
 /** Resource names Tilt knows about, or null when they cannot be listed (the logs call then reports the real error). */
 async function tiltResourceNames(port) {
@@ -25,8 +28,20 @@ async function tiltResourceNames(port) {
         return null;
     }
 }
+/** The project's services when every one declares `command` (they run as local processes), else null. */
+function nativeResources(projectRoot) {
+    try {
+        const resources = discoverResourcesFromRoot(projectRoot);
+        return isNativeProject(resources) ? resources : null;
+    }
+    catch {
+        // Discovery problems are reported by the commands that start the stack; logs still asks Tilt.
+        return null;
+    }
+}
 export const logsCommand = new Command("logs")
     .description("Print a bounded snapshot of recent logs from the running stack")
+    .showHelpAfterError("\nService names are not positional. Use: flisk logs --service <name>")
     .option("-s, --service <names...>", "Only these services (Tilt resource names)")
     .option("--tail <n>", "Number of most recent lines to return", String(DEFAULT_LOG_TAIL))
     .option("--since <duration>", "Only logs newer than this duration, for example 30s, 5m, 1h")
@@ -80,6 +95,29 @@ export const logsCommand = new Command("logs")
                 "Fix the read permission on .env, or move it out of the project",
             ]);
         }
+        // A project of `command` services keeps its output in .flisk/native/logs, so no Tilt is involved.
+        const resources = nativeResources(projectRoot);
+        if (resources) {
+            const known = resources.map((resource) => resource.name);
+            const unknown = services.filter((name) => !known.includes(name));
+            if (unknown.length > 0) {
+                const error = errorFactories.unknownServices(unknown, known);
+                fail("UNKNOWN_SERVICE", error.message, error.exitCode, error.suggestions);
+            }
+            const lines = readNativeLogLines(projectRoot, services.length > 0 ? services : known, {
+                tail,
+                sinceMs: options.since === undefined ? undefined : sinceMilliseconds(options.since),
+            });
+            if (options.json) {
+                console.log(JSON.stringify(redactValue(createMachineEnvelope({ services, tail, since: options.since ?? null, lines }), secrets)));
+                return;
+            }
+            const width = Math.max(0, ...lines.map((line) => line.resource.length));
+            for (const line of lines) {
+                console.log(redactSecrets(`${line.resource.padEnd(width)} | ${line.text}`, secrets));
+            }
+            return;
+        }
         if (!(await isTiltAvailable())) {
             fail("TILT_MISSING", "Tilt is not installed. Run: flisk doctor");
         }

package/cli/dist/commands/project.js

@@ -213,7 +213,19 @@ const DEFAULT_PROJECT_JSON = {
     },
     overrides: {},
 };
+/**
+ * Writes .flisk/project.json with the defaults `flisk project --yes` uses, and nothing else: no generated Tiltfile, Compose file,
+ * .env or engine copy. `flisk up` uses it to adopt a directory of `command` services as a project, so `flisk down` and
+ * `flisk doctor` find it afterwards.
+ */
+export function writeDefaultProjectConfig(projectRoot) {
+    const projectConfig = JSON.parse(JSON.stringify(DEFAULT_PROJECT_JSON));
+    projectConfig.project.name = basename(projectRoot) || "my-project";
+    ensureDirectory(join(projectRoot, ".flisk"));
+    writeJsonFile(join(projectRoot, ".flisk", PROJECT_JSON), projectConfig);
+}
 export const projectCommand = addYesOption(new Command("project"))
+    .alias("init")
     .description("Initialize or validate project-level master configuration")
     .argument("[template]", `Clone a starter example instead of a blank project (${Object.keys(PROJECT_TEMPLATES).join(", ")})`)
     .option("--path <dir>", "Directory to clone the template into (default: the template's repo name)")

package/cli/dist/commands/resource.js

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
 import { existsSync, mkdirSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
 import { DEFAULT_AGENT_RUNTIME, resolveAgentDurability, resolveAgentRuntime, } from "../agent-runtimes/registry.js";
@@ -90,7 +90,7 @@ export function resolveResourcePort(resourceType, value, assignedPort, resources
     }
     return port;
 }
-export function createServiceJson(name, type, stack, port, extraFeatures = [], frameworkId, languageId, agent) {
+export function createServiceJson(name, type, stack, port, extraFeatures = [], frameworkId, languageId, agent, basePath) {
     const framework = resolveFrontendFramework(type, frameworkId);
     // Only an explicit selection is persisted: a missing `language` has always meant Bun.
     const language = languageId === undefined ? undefined : resolveBackendLanguage(type, languageId);
@@ -129,11 +129,15 @@ export function createServiceJson(name, type, stack, port, extraFeatures = [], f
         stack,
         port,
         ...(framework ? { framework: framework.id } : {}),
+        // A server framework (Next.js) is served under /<name>/ with a base path, so the engine's default /health probe finds
+        // nothing there. Probe the framework's own health route under the same prefix.
+        ...(framework?.kind === "server" ? { healthCheckPath: `/${name}/health` } : {}),
         ...(backendFramework && type !== "mcp" && type !== "agent"
             ? { framework: backendFramework.id }
             : {}),
         ...(language ? { language: language.id } : {}),
         ...(type === "agent" && agent ? { agent } : {}),
+        ...(type === "frontend" && basePath ? { basePath } : {}),
     };
 }
 export function createByoServiceJson(name, stack, port, options) {
@@ -173,20 +177,26 @@ export function createPackageJson(name, type, frameworkId, prismaEnabled = false
         version: "0.0.1",
         type: "module",
         scripts: {
-            ...(isFrontend
+            ...(isFrontend && !framework?.scripts
                 ? {
                     predev: requireGeneratedViteConfig(`${AUTOGENERATED_DIR}/vite.config.frontend.autogenerated.ts`),
                     prebuild: requireGeneratedViteConfig(`${AUTOGENERATED_DIR}/vite.config.build.autogenerated.ts`),
                 }
                 : {}),
             dev: isFrontend
-                ? `vite --config ${AUTOGENERATED_DIR}/vite.config.frontend.autogenerated.ts`
+                ? (framework?.scripts?.dev ??
+                    `vite --config ${AUTOGENERATED_DIR}/vite.config.frontend.autogenerated.ts`)
                 : "bun run --watch src/index.ts",
             build: isFrontend
-                ? `tsc && vite build --config ${AUTOGENERATED_DIR}/vite.config.build.autogenerated.ts`
+                ? (framework?.scripts?.build ??
+                    `tsc && vite build --config ${AUTOGENERATED_DIR}/vite.config.build.autogenerated.ts`)
                 : "tsc",
-            // Backends and workers run `start` in their production image; doctor checks for it.
-            ...(isFrontend ? {} : { start: "bun run dist/index.js" }),
+            // Backends and workers run `start` in their production image; doctor checks for it. A server framework brings its own.
+            ...(isFrontend
+                ? framework?.scripts?.start
+                    ? { start: framework.scripts.start }
+                    : {}
+                : { start: "bun run dist/index.js" }),
             test: "vitest",
             lint: "biome check .",
             "lint:fix": "biome check . --write",
@@ -220,7 +230,7 @@ export function createPackageJson(name, type, frameworkId, prismaEnabled = false
             "@biomejs/biome": "^2.5.13",
             // vitest 5 peers on vite ^6.4.0 || ^7 || ^8; vite 5 makes `vitest run` fail at startup with
             // ERR_PACKAGE_PATH_NOT_EXPORTED ('./module-runner'), in every resource once it is hoisted.
-            ...(isFrontend ? { vite: "^6.4.1" } : {}),
+            ...(isFrontend && !framework?.scripts ? { vite: "^6.4.1" } : {}),
             ...(drizzleEnabled ? { "drizzle-kit": DRIZZLE_KIT_RANGE, "@types/pg": "^8.11.0" } : {}),
             ...(framework?.devDependencies ?? {}),
             ...(backendFramework?.devDependencies ?? {}),
@@ -269,6 +279,9 @@ export default defineConfig({
 `;
 export function createResourceTsconfig(resourceType, frameworkId) {
     const framework = resolveFrontendFramework(resourceType, frameworkId);
+    // A server framework (Next.js) owns its compiler settings: the SPA template's `rootDir`, `outDir` and declaration output do not apply.
+    if (framework?.tsconfig)
+        return framework.tsconfig;
     const backendFramework = resolveBackendFramework(resourceType, frameworkId);
     return {
         ...TSCONFIG_TEMPLATE,
@@ -380,7 +393,7 @@ export const resourceCommand = addYesOption(new Command("resource"))
     .description("Create a new resource (service) from scratch, or register an existing one")
     .argument("[name]", "Resource name (kebab-case)")
     .option("-t, --type <type>", "Resource type: backend, frontend, worker, mcp, agent, bring-your-own, sdk", "backend")
-    .option("--framework <id>", "Framework: frontend react (default), vue, svelte, preact, lit, solid, qwik, vanilla, tanstack-router; backend hono (default), express, elysia, fastify, nestjs, koa, h3 (list them with --frameworks)")
+    .option("--framework <id>", "Framework: frontend react (default), vue, svelte, preact, lit, solid, qwik, vanilla, tanstack-router, next; backend hono (default), express, elysia, fastify, nestjs, koa, h3 (list them with --frameworks)")
     .option("--frameworks", "List registered frameworks for the resource type and exit (--type frontend, --type backend)")
     .option("--language <id>", "Backend language: bun (default), python, go, rust, node")
     .option("-s, --stack <stack>", "Stack to assign resource to", "default")
@@ -394,6 +407,7 @@ export const resourceCommand = addYesOption(new Command("resource"))
     .option("--restart <policy>", "Compose restart policy: no, on-failure, unless-stopped, always (bring-your-own only; use no for one-shot jobs)")
     .option("--image <name>", "Docker image name instead of building from Dockerfile (for bring-your-own)")
     .option("--port <port>", "Port for the resource, within its type's range (default: next free port in that range)")
+    .option("--base-path <path>", "Base path for frontend routing (e.g., /storefront). Default is /{stack}s. Frontend only.")
     .option("--feature <feature...>", "Enable a resource feature (for example: prisma, drizzle)")
     .option("--runtime <id>", "Agent runtime (for agent only): custom (default)")
     .option("--durability <kind>", "Where agent sessions are checkpointed (for agent only): files (default, named volume) or postgres")
@@ -757,6 +771,10 @@ This file contains the resource configuration for Flisk.
         }
         if (resourceType === "frontend") {
             mkdirSync(resolve(fullPath, "public"), { recursive: true });
+            // A framework can keep its files in folders of its own (Next.js: src/app).
+            for (const file of frontendFramework?.createFiles(resourceName) ?? []) {
+                mkdirSync(dirname(resolve(fullPath, file.filename)), { recursive: true });
+            }
         }
         if (dddEnabled) {
             for (const layer of ["domain", "application", "infrastructure", "presentation"]) {
@@ -766,11 +784,19 @@ This file contains the resource configuration for Flisk.
         // Prepare file generation tasks
         const prismaEnabled = requestedFeatures.includes("prisma");
         const drizzleEnabled = requestedFeatures.includes("drizzle");
-        const serviceJson = createServiceJson(resourceName, resourceType, stackName, assignedPort, [...(dddEnabled ? ["ddd"] : []), ...requestedFeatures], scaffoldFrameworkId, options.language === undefined ? undefined : backendLanguage?.id, agentConfig);
+        const serviceJson = createServiceJson(resourceName, resourceType, stackName, assignedPort, [...(dddEnabled ? ["ddd"] : []), ...requestedFeatures], scaffoldFrameworkId, options.language === undefined ? undefined : backendLanguage?.id, agentConfig, resourceType === "frontend" ? options.basePath : undefined);
         const packageJson = createPackageJson(resourceName, resourceType, scaffoldFrameworkId, prismaEnabled, agentConfig, drizzleEnabled);
         if (prismaEnabled && resourceType === "backend") {
             serviceJson.dependsOn = [`${resourceName}-migrator`];
         }
+        // A frontend is wired to the first backend already in its stack, so its starter can call that API out of the box.
+        const frontendBackendName = resourceType === "frontend"
+            ? allResources.find((resource) => resource.stack === stackName && resource.type === "backend")?.name
+            : undefined;
+        if (frontendBackendName) {
+            serviceJson.backendName = frontendBackendName;
+            serviceJson.dependsOn = [frontendBackendName];
+        }
         const tasks = [
             {
                 type: "json",
@@ -829,7 +855,9 @@ This file contains the resource configuration for Flisk.
             });
         }
         else if (resourceType === "frontend") {
-            tasks.push(...(frontendFramework?.createFiles(resourceName).map((file) => ({
+            tasks.push(...(frontendFramework
+                ?.createFiles(resourceName, { backendName: frontendBackendName })
+                .map((file) => ({
                 ...file,
                 type: "text",
             })) ?? []));

package/cli/dist/commands/status.js

@@ -8,6 +8,8 @@ import { runCommand } from "../utils/errors.js";
 import { formatCount, showDetail, showStep } from "../utils/formatting.js";
 import { getHostPortPlan } from "../utils/host-port-config.js";
 import { createMachineEnvelope, writeMachineError } from "../utils/machine-output.js";
+import { nativeServiceStates } from "../utils/native-runtime.js";
+import { isNativeProject } from "../utils/native-service.js";
 import { findProjectRoot } from "../utils/paths.js";
 import { deriveServiceStates } from "../utils/service-runtime-state.js";
 import { groupSharedPostgres, readProjectName } from "../utils/shared-infra.js";
@@ -31,19 +33,30 @@ export const statusCommand = new Command("status")
         const sharedInfraGroup = projectName
             ? groupSharedPostgres(projectName, discovery.stacks)
             : null;
+        // A project of `command` services runs as local processes: its state comes from the run on record, not from Tilt.
+        const nativeStates = projectRoot && isNativeProject(discovery.resources)
+            ? nativeServiceStates(projectRoot, discovery.resources.map((resource) => resource.name))
+            : null;
         let tiltAvailable = false;
-        try {
-            tiltAvailable = await isTiltAvailable();
-        }
-        catch {
-            // Tilt not available (spawn error)
-            tiltAvailable = false;
+        if (!nativeStates) {
+            try {
+                tiltAvailable = await isTiltAvailable();
+            }
+            catch {
+                // Tilt not available (spawn error)
+                tiltAvailable = false;
+            }
         }
         if (!options.json) {
             showStep("Flisk Status\n");
-            console.log(chalk.bold("Tilt:"), tiltAvailable ? chalk.green("available") : chalk.red("not found"));
-            if (!tiltAvailable) {
-                showDetail("Install Tilt: https://docs.tilt.dev/install.html");
+            if (nativeStates) {
+                console.log(chalk.bold("Runtime:"), "local processes (no Docker, no Tilt)");
+            }
+            else {
+                console.log(chalk.bold("Tilt:"), tiltAvailable ? chalk.green("available") : chalk.red("not found"));
+                if (!tiltAvailable) {
+                    showDetail("Install Tilt: https://docs.tilt.dev/install.html");
+                }
             }
             console.log();
         }
@@ -53,8 +66,17 @@ export const statusCommand = new Command("status")
         // Tilt answers or its output cannot be read.
         let readiness = null;
         // The same look at Tilt feeds readiness and each service's state, so `flisk status` and `flisk ui` cannot disagree.
-        let serviceStates = null;
+        let serviceStates = nativeStates;
         const tiltPort = getTiltPollingPort(process.env.TILT_PORT);
+        // Port plan is best effort; service URLs are shown in both JSON and terminal output.
+        let portPlan = null;
+        try {
+            const root = findProjectRoot();
+            portPlan = root ? await getHostPortPlan(root, { inspectDocker: false }) : null;
+        }
+        catch {
+            // Port planning failed; service URLs will be omitted from terminal output.
+        }
         if (tiltAvailable) {
             const text = await tiltGetUiResources(tiltPort);
             // `tilt get` has no -f flag; resources come from the running Tilt's API on its port, the same source as readiness.
@@ -89,16 +111,24 @@ export const statusCommand = new Command("status")
             }
         }
         if (options.json) {
-            let portPlan = null;
-            try {
-                const root = findProjectRoot();
-                portPlan = root ? await getHostPortPlan(root, { inspectDocker: false }) : null;
-            }
-            catch {
-                // Port planning is best effort; stack ports then list only the Tilt UI.
-            }
             const errors = queryError ? [{ code: "TILT_STATUS_UNAVAILABLE", message: queryError }] : [];
+            // A native run answers the readiness question agents poll (data.tilt.readiness.ready) from its own run state.
+            if (nativeStates) {
+                const states = Object.entries(nativeStates);
+                const isRunning = states.some(([, state]) => state.status !== "unknown");
+                readiness = isRunning
+                    ? {
+                        ready: states.every(([, state]) => state.status === "ready"),
+                        failures: [],
+                        pending: states.filter(([, state]) => state.status !== "ready").length,
+                        timedOut: false,
+                        enabled: states.map(([name]) => name),
+                    }
+                    : null;
+            }
             const data = {
+                // Only a project of local processes says so; a container project's report keeps its shape.
+                ...(nativeStates ? { runtime: "native" } : {}),
                 tilt: {
                     available: tiltAvailable,
                     resourcesQueried: options.tilt && tiltAvailable,
@@ -178,9 +208,17 @@ export const statusCommand = new Command("status")
                     : state.status === "error"
                         ? chalk.red("✗")
                         : chalk.yellow("…");
-                showDetail(`${mark} ${resource.name}  ${state.status}${state.reason ? ` (${state.reason})` : ""}`);
+                const ports = buildServicePorts(resource, portPlan?.ingressHttp);
+                const urlPart = ports.url ? ` → ${ports.url}` : "";
+                showDetail(`${mark} ${resource.name}${urlPart}  ${state.status}${state.reason ? ` (${state.reason})` : ""}`);
             }
         }
+        else if (discovery.resources.length > 0) {
+            // Without a running Tilt, no service state can be read. Say so instead of printing nothing.
+            console.log();
+            console.log(chalk.bold("Services:"));
+            showDetail(`unknown: no Tilt answers on port ${tiltPort}, so nothing is confirmed running. Start with: flisk up`);
+        }
         if (options.tilt && tiltAvailable) {
             console.log();
             showStep("Tilt Resources:");