@flisk-sh/flisk 1.4.1 → 1.4.5

package/cli/dist/backend-languages/bun.js

@@ -24,9 +24,14 @@ app.get('/health/db', async (c) => {
 `
         : "";
     return `import { Hono } from 'hono';
+import { cors } from 'hono/cors';
 ${drizzleImports}
 const app = new Hono();
 
+// The frontend runs on its own *.localhost origin (app.<project>.localhost), so the browser needs CORS to call this API.
+const LOCAL_FRONTEND_ORIGIN = /^https?:\\/\\/([a-z0-9-]+\\.)+localhost(:\\d+)?$/;
+app.use('*', cors({ origin: (origin) => (LOCAL_FRONTEND_ORIGIN.test(origin) ? origin : undefined) }));
+
 // Health check endpoint (required by TILT_RESOURCE_DEFAULTS.star)
 app.get('/health', (c) => {
   return c.json({ status: 'ok', service: '${name}' });

package/cli/dist/backend-languages/go.js

@@ -34,7 +34,9 @@ import (
 func writeJSON(w http.ResponseWriter, status int, body any) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)
-	_ = json.NewEncoder(w).Encode(body)
+	if err := json.NewEncoder(w).Encode(body); err != nil {
+		log.Printf("failed to encode JSON response: %v", err)
+	}
 }
 
 func newMux() *http.ServeMux {

package/cli/dist/cli.js

@@ -12,6 +12,7 @@ import { showHelp } from "./commands/help.js";
 import { createProgram } from "./program.js";
 import { ensureGlobalInstall } from "./utils/cli-command.js";
 import { formatColdPreflight, runColdPreflight } from "./utils/cold-preflight.js";
+import { stopDemoStack } from "./utils/demo-reset.js";
 import { unknownHelpTarget } from "./utils/help-command.js";
 import { bareTemplateArg } from "./utils/project-templates.js";
 const program = createProgram();
@@ -68,6 +69,7 @@ if (templateArg) {
         }
     }
     const destination = isAbsolute(targetName) ? targetName : resolve(cwd(), targetName);
+    console.log(chalk.gray(`📁 Demo folder: ${destination}`));
     // Reusing an existing checkout is what keeps a second take free: the clone and the
     // dependency install are skipped, so the recording starts on the interesting part.
     let reused = false;
@@ -85,6 +87,13 @@ if (templateArg) {
             await openUrl(running.url);
             process.exit(0);
         }
+        // Take the old stack down before its folder goes, so a Traefik left behind does not keep port 80.
+        try {
+            stopDemoStack(destination);
+        }
+        catch (error) {
+            console.log(chalk.yellow(`Could not stop the previous demo stack: ${error.message}`));
+        }
         if (keep) {
             reused = true;
         }

package/cli/dist/commands/completion.js

@@ -463,7 +463,14 @@ _flisk_resources() {
 ${subCommandLists}
 
 ${typeValueFunctions}
-compdef _flisk flisk
+
+# Autoloaded from fpath, this file is the body of _flisk, so run it now to complete the first TAB.
+# Sourced (\`source <(flisk completion zsh)\`), register it instead.
+if [ "$funcstack[1]" = "_flisk" ]; then
+    _flisk "$@"
+else
+    compdef _flisk flisk
+fi
 `;
 }
 /** The `_arguments` spec of one flag, with the values it completes when it has them. */

package/cli/dist/commands/config.js

@@ -9,7 +9,8 @@ import { hasVerdaccioLicense } from "../generator/extension-fetch.js";
 import { generateMasterConfigs, readProjectConfig, TemplateEngine, verifyMasterConfigs, } from "../generator/template-engine.js";
 import { isMasterConfigFileName } from "../types/index.js";
 import { assertValid, handleDryRun } from "../utils/command-helpers.js";
-import { MASTER_CONFIG_FILES, PROJECT_JSON } from "../utils/constants.js";
+import { explainConfigFile } from "../utils/config-explain.js";
+import { MASTER_CONFIG_FILES, PROJECT_JSON, RESOURCE_DEFAULTS_FILE, TECH_STACK_FILE, } from "../utils/constants.js";
 import { clearDiscoveryCache } from "../utils/discovery-context.js";
 import { checkPrismaConsistency } from "../utils/doctor-wiring.js";
 import { errorFactories, requireProjectRoot, runCommand, showError } from "../utils/errors.js";
@@ -20,6 +21,12 @@ import { SERVICE_MANIFEST_SCHEMA_VERSION, validateServiceManifest, } from "../ut
 import { discoverResourcesWithProblems, discoverServiceManifestPaths, warnAboutSkippedFiles, } from "../utils/services.js";
 import { evaluateSharedPlatformPostgres } from "../utils/shared-platform-postgres.js";
 import { validateOptionalInfraService } from "../utils/validation.js";
+/** Human wording for `flisk config explain`, one line per drift outcome. */
+const DRIFT_LABELS = {
+    "blocks-up": "yes, until the edit is removed or --ignore-drift is passed",
+    none: "no",
+    unknown: "unknown",
+};
 export const configCommand = new Command("config")
     .description("Manage project configuration and regenerate master files")
     .addCommand(new Command("regenerate")
@@ -36,72 +43,104 @@ export const configCommand = new Command("config")
             const newFiles = engine.generateAll(projectConfig);
             const outputDir = join(projectRoot, ".flisk", ".flisk-out");
             const filesToCheck = MASTER_CONFIG_FILES;
+            const fileGroups = [
+                {
+                    title: "📋 Core orchestration",
+                    files: [TECH_STACK_FILE, RESOURCE_DEFAULTS_FILE],
+                    description: "Tilt tech stack and resource defaults; drives all service generation",
+                },
+                {
+                    title: "📦 Project spec",
+                    files: ["spec.master"],
+                    description: "Compiled project specification; used by Tilt for service discovery",
+                },
+            ];
             let hasChanges = false;
-            for (const filename of filesToCheck) {
-                // Runtime validation with type guard eliminates type assertion
-                if (!isMasterConfigFileName(filename)) {
-                    continue; // Skip unknown files (shouldn't happen with const array)
-                }
-                const newContent = newFiles[filename];
-                const filePath = join(outputDir, filename);
-                if (!existsSync(filePath)) {
-                    console.log(chalk.yellow(`📁 ${filename}`));
-                    console.log(chalk.gray("   Status: NEW (file does not exist)\n"));
-                    hasChanges = true;
-                    continue;
-                }
-                const currentContent = readFileSync(filePath, "utf-8");
-                if (currentContent === newContent) {
-                    console.log(chalk.green(`✓ ${filename}`));
-                    console.log(chalk.gray("   Status: No changes\n"));
-                }
-                else {
-                    console.log(chalk.yellow(`📝 ${filename}`));
-                    console.log(chalk.gray("   Status: MODIFIED"));
-                    const currentLines = currentContent.split("\n").length;
-                    const newLines = newContent.split("\n").length;
-                    const lineDiff = newLines - currentLines;
-                    if (lineDiff > 0) {
-                        console.log(chalk.gray(`   Lines: ${currentLines} → ${newLines} (+${lineDiff})`));
+            for (const group of fileGroups) {
+                let groupHasChanges = false;
+                const groupChanges = [];
+                for (const filename of group.files) {
+                    if (!filesToCheck.includes(filename))
+                        continue;
+                    if (!isMasterConfigFileName(filename))
+                        continue;
+                    const newContent = newFiles[filename];
+                    const filePath = join(outputDir, filename);
+                    if (!existsSync(filePath)) {
+                        groupHasChanges = true;
+                        groupChanges.push({ filename, isNew: true, lineDiff: 0, diffLines: [] });
+                        continue;
                     }
-                    else if (lineDiff < 0) {
-                        console.log(chalk.gray(`   Lines: ${currentLines} → ${newLines} (${lineDiff})`));
-                    }
-                    else {
-                        console.log(chalk.gray(`   Lines: ${currentLines} (content changed)`));
-                    }
-                    const currentLinesArr = currentContent.split("\n");
-                    const newLinesArr = newContent.split("\n");
-                    let firstDiffLine = -1;
-                    for (let i = 0; i < Math.max(currentLinesArr.length, newLinesArr.length); i++) {
-                        if (currentLinesArr[i] !== newLinesArr[i]) {
-                            firstDiffLine = i;
-                            break;
+                    const currentContent = readFileSync(filePath, "utf-8");
+                    if (currentContent !== newContent) {
+                        groupHasChanges = true;
+                        const currentLines = currentContent.split("\n").length;
+                        const newLines = newContent.split("\n").length;
+                        const lineDiff = newLines - currentLines;
+                        const currentLinesArr = currentContent.split("\n");
+                        const newLinesArr = newContent.split("\n");
+                        let firstDiffLine = -1;
+                        for (let i = 0; i < Math.max(currentLinesArr.length, newLinesArr.length); i++) {
+                            if (currentLinesArr[i] !== newLinesArr[i]) {
+                                firstDiffLine = i;
+                                break;
+                            }
                         }
-                    }
-                    if (firstDiffLine >= 0) {
-                        console.log(chalk.gray(`   First change around line ${firstDiffLine + 1}:`));
-                        const contextStart = Math.max(0, firstDiffLine - 1);
-                        const contextEnd = Math.min(currentLinesArr.length, firstDiffLine + 2);
-                        for (let i = contextStart; i < contextEnd; i++) {
-                            const line = currentLinesArr[i];
-                            const newLine = newLinesArr[i];
-                            if (line !== newLine) {
-                                if (line !== undefined) {
-                                    console.log(chalk.red(`     - ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
+                        const diffLines = [];
+                        if (firstDiffLine >= 0) {
+                            const contextStart = Math.max(0, firstDiffLine - 1);
+                            const contextEnd = Math.min(currentLinesArr.length, firstDiffLine + 2);
+                            for (let i = contextStart; i < contextEnd; i++) {
+                                const line = currentLinesArr[i];
+                                const newLine = newLinesArr[i];
+                                if (line !== newLine) {
+                                    if (line !== undefined) {
+                                        diffLines.push(chalk.red(`     - ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
+                                    }
+                                    if (newLine !== undefined) {
+                                        diffLines.push(chalk.green(`     + ${newLine.substring(0, 60)}${newLine.length > 60 ? "..." : ""}`));
+                                    }
                                 }
-                                if (newLine !== undefined) {
-                                    console.log(chalk.green(`     + ${newLine.substring(0, 60)}${newLine.length > 60 ? "..." : ""}`));
+                                else {
+                                    diffLines.push(chalk.gray(`       ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
                                 }
                             }
+                        }
+                        groupChanges.push({ filename, isNew: false, lineDiff, diffLines });
+                    }
+                }
+                if (groupHasChanges) {
+                    console.log(chalk.blue(`\n${group.title}`));
+                    console.log(chalk.gray(`   ${group.description}\n`));
+                    for (const change of groupChanges) {
+                        if (change.isNew) {
+                            console.log(chalk.yellow(`  📁 ${change.filename}`));
+                            console.log(chalk.gray("     Status: NEW (file does not exist)\n"));
+                        }
+                        else {
+                            console.log(chalk.yellow(`  📝 ${change.filename}`));
+                            console.log(chalk.gray("     Status: MODIFIED"));
+                            if (change.lineDiff > 0) {
+                                console.log(chalk.gray(`     Lines: +${change.lineDiff}`));
+                            }
+                            else if (change.lineDiff < 0) {
+                                console.log(chalk.gray(`     Lines: ${change.lineDiff}`));
+                            }
                             else {
-                                console.log(chalk.gray(`       ${line.substring(0, 60)}${line.length > 60 ? "..." : ""}`));
+                                console.log(chalk.gray("     Lines: content changed"));
                             }
+                            for (const diffLine of change.diffLines) {
+                                console.log(diffLine);
+                            }
+                            console.log("");
                         }
                     }
-                    console.log("");
                     hasChanges = true;
                 }
+                else {
+                    console.log(chalk.green(`\n✅ ${group.title} — all up to date`));
+                    console.log(chalk.gray(`   ${group.description}\n`));
+                }
             }
             if (hasChanges) {
                 console.log(chalk.blue("💡 Run without --dry-run to apply these changes.\n"));
@@ -268,6 +307,42 @@ export const configCommand = new Command("config")
         return;
     }
     await runCommand(action);
+}))
+    .addCommand(new Command("explain")
+    .description("Explain whether a project file is Flisk-generated and what editing it does on flisk up")
+    .argument("<file>", "Project file to explain, relative to the current directory or absolute")
+    .option("--json", "Emit a machine-readable explanation")
+    .action(async (file, options) => {
+    const action = async () => {
+        const projectRoot = options.json ? findProjectRoot() : requireProjectRoot();
+        if (!projectRoot)
+            throw errorFactories.notInProject();
+        const explanation = explainConfigFile(projectRoot, file);
+        if (options.json) {
+            console.log(JSON.stringify(createMachineEnvelope(explanation)));
+            return;
+        }
+        console.log(chalk.blue(`${explanation.file}\n`));
+        console.log(`  Ownership: ${explanation.ownership}`);
+        console.log(`  ${explanation.reason}`);
+        if (explanation.source)
+            console.log(`  Source: ${explanation.source}`);
+        console.log(`  Edited now: ${explanation.isEditedNow ? "yes" : "no"}`);
+        console.log(`  Editing it blocks flisk up: ${DRIFT_LABELS[explanation.driftOnUp]}`);
+        console.log(chalk.blue("\nNext:"));
+        for (const step of explanation.next)
+            console.log(chalk.gray(`  - ${step}`));
+    };
+    if (options.json) {
+        try {
+            await action();
+        }
+        catch (error) {
+            writeMachineError(error);
+        }
+        return;
+    }
+    await runCommand(action);
 }))
     .addCommand(new Command("edit").description("Open .flisk/project.json in your $EDITOR").action(async () => {
     await runCommand(async () => {

package/cli/dist/commands/doctor.js

@@ -291,7 +291,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 +310,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 +328,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 +350,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 +365,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 +443,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 +458,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 +466,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 +491,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 +523,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 +536,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",
         };
     }
 }

package/cli/dist/commands/logs.js

@@ -27,6 +27,7 @@ async function tiltResourceNames(port) {
 }
 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")

package/cli/dist/commands/project.js

@@ -214,6 +214,7 @@ const DEFAULT_PROJECT_JSON = {
     overrides: {},
 };
 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

@@ -55,6 +55,15 @@ export const statusCommand = new Command("status")
         // The same look at Tilt feeds readiness and each service's state, so `flisk status` and `flisk ui` cannot disagree.
         let serviceStates = null;
         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,14 +98,6 @@ 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 }] : [];
             const data = {
                 tilt: {
@@ -178,9 +179,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:");