@flisk-sh/flisk 1.4.1 → 1.4.5

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

@@ -61,7 +61,7 @@ export function requireVerifiedDockerVersions(result) {
         fix: result.fix ?? "Start Docker and ensure Docker Engine 25+ and Compose 2.20.2+ are installed.",
     };
 }
-function usesPrisma(projectRoot) {
+export function usesPrisma(projectRoot) {
     try {
         return discoverResourcesFromRoot(projectRoot).some((resource) => {
             return resource.config?.featuresEnabled?.includes("prisma") ?? false;
@@ -120,9 +120,10 @@ export async function runColdPreflight(opts = {}) {
     const bunPath = bunNeeded ? findOnPath("bun") : undefined;
     if (bunPath) {
         try {
+            // A cold start of bun can pass 3s on a busy machine; a timeout there reads as "not installed".
             const version = execFileSync(bunPath, ["--version"], {
                 encoding: "utf-8",
-                timeout: 3000,
+                timeout: 10_000,
             }).trim();
             bun = bunMeetsFloor(version);
         }

package/cli/dist/utils/config-explain.js

@@ -0,0 +1,197 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { FLISK_GENERATED_MARKER, ProjectConfigNotFoundError, verifyMasterConfigs, } from "../generator/template-engine.js";
+import { AUTOGENERATED_DIR, PACKAGE_JSON, PROJECT_JSON, SERVICE_JSON, TILTIGNORE_FILE, } from "./constants.js";
+import { FliskError } from "./errors.js";
+import { isFliskGeneratedPath } from "./generated-paths.js";
+/** Snapshot directory `flisk up` writes next to a service's `.autogenerated/` outputs. */
+const CONTRACT_DIR = ".flisk-contract";
+/** Generated service file that is exempt from the hand-edit check. */
+const SERVICE_YAML = "service.yaml";
+/**
+ * Explains one project file using the generated-path allowlist and the hand-edit check that `flisk up` runs.
+ * `file` resolves against the current directory, as shell paths do. Throws a FliskError for a path outside the
+ * project, a missing file, or a directory.
+ */
+export function explainConfigFile(projectRoot, file) {
+    const absolute = resolve(file);
+    const rel = relative(projectRoot, absolute).split(sep).join("/");
+    if (rel === "" || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) {
+        throw new FliskError(`${file} is outside the project`, ["Pass a file inside the project root"]);
+    }
+    if (!existsSync(absolute)) {
+        throw new FliskError(`File not found: ${rel}`, ["Check the path and try again"]);
+    }
+    if (!statSync(absolute).isFile()) {
+        throw new FliskError(`Not a file: ${rel}`, ["Pass a file, not a directory"]);
+    }
+    const isEditedNow = isHandEditedNow(projectRoot, rel);
+    if (!isFliskGeneratedPath(rel)) {
+        return userOwned(rel, isEditedNow);
+    }
+    const segments = rel.split("/");
+    const autogenIndex = segments.indexOf(AUTOGENERATED_DIR);
+    if (autogenIndex >= 0) {
+        return explainServiceOutput(projectRoot, rel, segments, autogenIndex, isEditedNow);
+    }
+    // The allowlist names these paths, but the path alone does not show who wrote the file. Flisk creates
+    // package.json only when it is missing and never overwrites an existing one, so it is the user's to edit.
+    if (rel === PACKAGE_JSON) {
+        return {
+            file: rel,
+            ownership: "user-owned",
+            reason: "Flisk creates package.json only when it is missing and never overwrites an existing one.",
+            source: null,
+            driftOnUp: "none",
+            isEditedNow,
+            next: ["Edit it directly."],
+        };
+    }
+    // A root .tiltignore without Flisk's marker belongs to the team, and Flisk leaves it in place.
+    if (rel === TILTIGNORE_FILE &&
+        !readFileSync(absolute, "utf-8").includes(FLISK_GENERATED_MARKER)) {
+        return {
+            file: rel,
+            ownership: "user-owned",
+            reason: "This .tiltignore has no Flisk generated marker, so Flisk leaves it in place.",
+            source: null,
+            driftOnUp: "none",
+            isEditedNow,
+            next: ["Edit it directly."],
+        };
+    }
+    if (isProjectOutput(rel)) {
+        return {
+            file: rel,
+            ownership: "generated",
+            reason: "Generated from .flisk/project.json.",
+            source: `.flisk/${PROJECT_JSON}`,
+            driftOnUp: "none",
+            isEditedNow,
+            next: [
+                `Edit .flisk/${PROJECT_JSON} instead.`,
+                "`flisk config regenerate` rewrites this file from project.json and discards edits.",
+            ],
+        };
+    }
+    return {
+        file: rel,
+        ownership: "generated",
+        reason: "Written by Flisk; this file does not record the input it is generated from.",
+        source: null,
+        driftOnUp: "none",
+        isEditedNow,
+        next: ["Do not edit it; Flisk writes it when it generates outputs."],
+    };
+}
+function userOwned(rel, isEditedNow) {
+    const base = { file: rel, ownership: "user-owned", isEditedNow };
+    if (rel === `.flisk/${PROJECT_JSON}`) {
+        return {
+            ...base,
+            reason: "Flisk input: the project config that generated outputs are built from.",
+            source: null,
+            driftOnUp: "none",
+            next: ["Edit it, then run `flisk config regenerate`."],
+        };
+    }
+    if (rel.split("/").pop() === SERVICE_JSON) {
+        return {
+            ...base,
+            reason: "Flisk input: the service manifest that generated service files are built from.",
+            source: null,
+            driftOnUp: "none",
+            next: ["Edit it, then run `flisk up` to regenerate the service's outputs."],
+        };
+    }
+    return {
+        ...base,
+        reason: "Not in Flisk's generated-file allowlist, so Flisk does not write it.",
+        source: null,
+        driftOnUp: "none",
+        next: ["Edit it directly."],
+    };
+}
+function explainServiceOutput(projectRoot, rel, segments, autogenIndex, isEditedNow) {
+    const serviceDir = segments.slice(0, autogenIndex).join("/");
+    const source = serviceDir ? `${serviceDir}/${SERVICE_JSON}` : SERVICE_JSON;
+    if (!existsSync(join(projectRoot, source))) {
+        return {
+            file: rel,
+            ownership: "unknown",
+            reason: `${AUTOGENERATED_DIR}/ has no ${SERVICE_JSON} beside it, so Flisk cannot tell which input produces this file.`,
+            source: null,
+            driftOnUp: "unknown",
+            isEditedNow,
+            next: ["Find where the file came from before editing it."],
+        };
+    }
+    const inside = segments.slice(autogenIndex + 1);
+    if (inside[0] === CONTRACT_DIR) {
+        return {
+            file: rel,
+            ownership: "generated",
+            reason: "Flisk's snapshot of the generated files; `flisk up` reads it to detect hand edits.",
+            source,
+            driftOnUp: "none",
+            isEditedNow,
+            next: ["Do not edit it; Flisk writes it when it generates outputs."],
+        };
+    }
+    const insidePath = inside.join("/");
+    if (insidePath === SERVICE_YAML) {
+        return {
+            file: rel,
+            ownership: "generated",
+            reason: "Runtime discovery file written by the Tilt extension; exempt from the hand-edit check.",
+            source,
+            driftOnUp: "none",
+            isEditedNow,
+            next: [`Do not edit it; edit ${source} instead.`],
+        };
+    }
+    const snapshot = join(projectRoot, serviceDir, AUTOGENERATED_DIR, CONTRACT_DIR, insidePath);
+    if (!existsSync(snapshot)) {
+        return {
+            file: rel,
+            ownership: "generated",
+            reason: `Generated from ${source}. Flisk has no snapshot of this file, so it cannot tell whether an edit would block flisk up.`,
+            source,
+            driftOnUp: "unknown",
+            isEditedNow,
+            next: ["Run `flisk up` to write the snapshots, then explain the file again."],
+        };
+    }
+    return {
+        file: rel,
+        ownership: "generated",
+        reason: `Generated from ${source}.`,
+        source,
+        driftOnUp: "blocks-up",
+        isEditedNow,
+        next: [
+            `Edit ${source} instead, then run \`flisk up\`.`,
+            "Discard a hand edit with `flisk config regenerate`.",
+            "Keep a hand edit on purpose with `flisk up --ignore-drift`.",
+        ],
+    };
+}
+function isProjectOutput(rel) {
+    return (rel.startsWith(".flisk/.flisk-out/") ||
+        rel === "Tiltfile" ||
+        /^TILT_[^/]+\.star$/.test(rel) ||
+        rel === TILTIGNORE_FILE);
+}
+/** The same hand-edit list `flisk up` blocks on, so explain and the gate cannot disagree. */
+function isHandEditedNow(projectRoot, rel) {
+    try {
+        return verifyMasterConfigs(projectRoot).handEdited.includes(rel);
+    }
+    catch (error) {
+        if (error instanceof ProjectConfigNotFoundError)
+            return false;
+        throw error;
+    }
+}

package/cli/dist/utils/demo-reset.js

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Stop the stack of an existing demo folder before the folder is deleted. Deleting the folder alone leaves its
+ * containers running, and a standalone Traefik that stays up keeps port 80 for the next run.
+ * Returns true when a Flisk project was found and its `flisk down` ran.
+ */
+export function stopDemoStack(projectDir, runDown = runFliskDown) {
+    if (!existsSync(join(projectDir, ".flisk", "project.json")))
+        return false;
+    runDown(projectDir);
+    return true;
+}
+function runFliskDown(projectDir) {
+    execFileSync(process.execPath, [process.argv[1] ?? "flisk", "down", "--yes"], {
+        cwd: projectDir,
+        stdio: "inherit",
+    });
+}

package/cli/dist/utils/discovery-paths.js

@@ -52,12 +52,18 @@ export function readDiscoveryPaths(projectRoot) {
     const configPath = join(projectRoot, ".flisk", PROJECT_JSON);
     if (!existsSync(configPath))
         return DEFAULT_DISCOVERY_PATHS;
+    let reason = "discovery.paths must be an array of strings";
     try {
         const paths = JSON.parse(readFileSync(configPath, "utf-8"))?.discovery?.paths;
+        if (paths === undefined)
+            return DEFAULT_DISCOVERY_PATHS;
         if (Array.isArray(paths) && paths.every((p) => typeof p === "string"))
             return paths;
     }
-    catch { }
+    catch (error) {
+        reason = String(error);
+    }
+    console.warn(`Ignoring discovery configuration in ${configPath}: ${reason}; using default paths: ${DEFAULT_DISCOVERY_PATHS.join(", ")}`);
     return DEFAULT_DISCOVERY_PATHS;
 }
 /** Whether Tilt's discovery would find a service.json in `resourceDir` given `patterns`. */

package/cli/dist/utils/host-port-plan.js

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
 import { createServer } from "node:net";
+import { FliskError } from "./errors.js";
 import { hasLocalListener } from "./port-listener-probe.js";
 export const DEFAULT_HOST_PORT_RANGES = {
     ingressHttp: { start: 8080, end: 8180 },
@@ -43,7 +44,7 @@ export async function isHostPortAvailable(port) {
 function parsePort(name, value) {
     const port = Number(value);
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
-        throw new Error(`${name} must be an integer between 1 and 65535 (received ${JSON.stringify(value)})`);
+        throw new FliskError(`${name} must be an integer between 1 and 65535 (received ${JSON.stringify(value)})`, ["Provide a valid port number between 1 and 65535"], 1);
     }
     return port;
 }
@@ -74,11 +75,15 @@ export async function createHostPortPlan(options = {}) {
                 break;
             }
             if (explicit) {
-                throw new Error(`${ENV_KEYS[key]}=${port} is already in use. Choose a free host port and retry.`);
+                throw new FliskError(`${ENV_KEYS[key]}=${port} is already in use. Choose a free host port and retry.`, [
+                    "Choose a different free host port or unset the environment variable to use fallback ranges",
+                ], 1);
             }
         }
         if (chosen === undefined) {
-            throw new Error(`No available host port in ${range.start}-${range.end} for ${key}. Set ${ENV_KEYS[key]} to a free port and retry.`);
+            throw new FliskError(`No available host port in ${range.start}-${range.end} for ${key}. Set ${ENV_KEYS[key]} to a free port and retry.`, [
+                `Free up port range ${range.start}-${range.end} or set ${ENV_KEYS[key]} to an available port`,
+            ], 1);
         }
         reserved.add(chosen);
         selected[key] = chosen;

package/cli/dist/utils/port-conflict-fix.js

@@ -1,25 +1,27 @@
-// Copyright (c) 2026 Flisk Landscape contributors
-// SPDX-License-Identifier: MIT
 /** The env var that moves each host port Flisk publishes. Services publish no host ports, so only these conflict. */
 const PORT_ENV_VARS = {
     "80": "FLISK_HTTP_PORT",
     "443": "FLISK_HTTPS_PORT",
     "5432": "FLISK_POSTGRES_PORT",
 };
-/**
- * The next step for a host port another process already holds. The occupant is not named: finding it needs the OS, so
- * the command that finds it is given instead.
- */
-export function portConflictFix(message) {
+/** The host port a conflict message is about, or null when the message is not a port conflict. */
+export function conflictPort(message) {
     // The raw Docker error can reach the report when the readiness check fails before the summary runs.
     const match = message.match(/^host port (\d+) is already allocated$/) ??
         message.match(/Bind for [^ ]+:(\d+) failed: port is already allocated/i);
-    if (!match)
+    return match ? Number(match[1]) : null;
+}
+/**
+ * The next step for a host port another process already holds. When the occupant is known it is named; otherwise the
+ * command that finds it is given instead.
+ */
+export function portConflictFix(message, occupant = null) {
+    const port = conflictPort(message);
+    if (port === null)
         return null;
-    const port = match[1];
-    const find = `find it with: lsof -nP -iTCP:${port} -sTCP:LISTEN`;
-    const envVar = PORT_ENV_VARS[port];
-    if (!envVar)
-        return `Fix: stop the process using port ${port} (${find})`;
-    return `Fix: stop the process using port ${port} (${find}), or set ${envVar} to a free port and run flisk up`;
+    const envVar = PORT_ENV_VARS[String(port)];
+    const body = occupant
+        ? `Fix: port ${port} is held by ${occupant.command} (pid ${occupant.pid}). Stop it`
+        : `Fix: stop the process using port ${port} (find it with: lsof -nP -iTCP:${port} -sTCP:LISTEN)`;
+    return envVar ? `${body}, or set ${envVar} to a free port and run flisk up` : body;
 }

package/cli/dist/utils/port-occupant.js

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+const run = (command, args) => execFileSync(command, args, {
+    encoding: "utf-8",
+    stdio: "pipe",
+    timeout: 5000,
+    windowsHide: true,
+});
+/**
+ * The process listening on `port`, or null when it cannot be told (no lsof, Windows, nothing listens, or the process
+ * exited before ps could read it). Callers must treat null as "unknown", not as "free".
+ */
+export function findPortOccupant(port, platform = process.platform, commandRunner = run) {
+    if (platform === "win32")
+        return null;
+    try {
+        const [first] = commandRunner("lsof", ["-nP", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"])
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter(Boolean);
+        if (!first)
+            return null;
+        const pid = Number(first);
+        const name = commandRunner("ps", ["-p", first, "-o", "comm="]).trim();
+        if (!Number.isInteger(pid) || !name)
+            return null;
+        return { pid, command: basename(name) };
+    }
+    catch {
+        // lsof exits 1 when nothing listens, and may be missing.
+        return null;
+    }
+}

package/cli/dist/utils/project-features.js

@@ -70,22 +70,13 @@ export const PROJECT_FEATURES = {
     },
 };
 /**
- * Get all enabled project features
+ * Get all enabled project features: those on by default plus those switched
+ * on in `optional_infra`. Each feature appears once, in `PROJECT_FEATURES`
+ * order. Names that are not features are ignored, and `false` does not turn
+ * off a feature that is on by default.
  */
 export function getEnabledProjectFeatures(optional_infra) {
-    const enabled = [];
-    for (const [key, feature] of Object.entries(PROJECT_FEATURES)) {
-        if (feature.enabled_by_default) {
-            enabled.push(key);
-        }
-    }
-    // Add optional features if enabled
-    if (optional_infra) {
-        for (const [key, isEnabled] of Object.entries(optional_infra)) {
-            if (isEnabled && PROJECT_FEATURES[key]) {
-                enabled.push(key);
-            }
-        }
-    }
-    return enabled;
+    return Object.entries(PROJECT_FEATURES)
+        .filter(([key, feature]) => feature.enabled_by_default || optional_infra?.[key] === true)
+        .map(([key]) => key);
 }

package/cli/dist/utils/project-templates.js

@@ -1,37 +1,37 @@
 /** Public starter repositories plus the bundled default product example. */
 export const PROJECT_TEMPLATES = {
     demo: {
-        repo: "https://github.com/flisk-sh/tdk-restaurant-example.git",
+        repo: "https://github.com/flisk-sh/flisk-restaurant-example.git",
         description: "The demo stack: restaurant ops with reservations, kitchen and floor control",
         fixedDir: "flisk-demo",
     },
     restaurant: {
-        repo: "https://github.com/flisk-sh/tdk-restaurant-example.git",
+        repo: "https://github.com/flisk-sh/flisk-restaurant-example.git",
         description: "Restaurant ops: reservations, kitchen, floor control (Hono + Vite + Bun)",
     },
     saas: {
-        repo: "https://github.com/flisk-sh/tdk-saas-starter.git",
+        repo: "https://github.com/flisk-sh/flisk-saas-starter.git",
         description: "SaaS starter: account dashboard and a working checkout button (Hono + Vite + Bun)",
     },
     erp: {
-        repo: "https://github.com/flisk-sh/tdk-erp-system.git",
+        repo: "https://github.com/flisk-sh/flisk-erp-system.git",
         description: "Enterprise ERP: 100 microservices across 7 business domains",
     },
     "user-management": {
-        repo: "https://github.com/flisk-sh/tdk-user-management.git",
+        repo: "https://github.com/flisk-sh/flisk-user-management.git",
         description: "User/auth management services",
     },
     ecommerce: {
-        repo: "https://github.com/flisk-sh/tdk-ecommerce-example.git",
+        repo: "https://github.com/flisk-sh/flisk-ecommerce-example.git",
         description: "Vue 3 storefront and Hono catalog API (needs Flisk 1.3.75+ for --framework vue)",
     },
     example: {
-        repo: "https://github.com/flisk-sh/tdk-example.git",
+        repo: "https://github.com/flisk-sh/flisk-example.git",
         bundledPath: "examples/tdk-example",
         description: "Hono + Postgres + NATS worker + Vite example with a routed write path",
     },
     "agent-stack": {
-        repo: "https://github.com/flisk-sh/tdk-agent-stack.git",
+        repo: "https://github.com/flisk-sh/flisk-agent-stack.git",
         description: "AI agent stack: Bun agent + MCP tool server + Postgres + NATS",
     },
 };

package/cli/dist/utils/resource-features.js

@@ -160,15 +160,15 @@ export const RESOURCE_FEATURES = {
 /**
  * Get default features for a resource type
  */
-export function getDefaultFeaturesForResourceType(appType) {
+export function getDefaultFeaturesForResourceType(resourceType) {
     // bring-your-own doesn't generate application code, so no features
-    if (appType === BRING_YOUR_OWN_TYPE) {
+    if (resourceType === BRING_YOUR_OWN_TYPE) {
         return [];
     }
     const defaults = [];
     for (const [key, feature] of Object.entries(RESOURCE_FEATURES)) {
         if (feature.enabled_by_default &&
-            feature.applies_to.includes(appType) &&
+            feature.applies_to.includes(resourceType) &&
             // Only include if it's something users control via features array
             ["api-client", "env-config", "api-index", "prisma"].includes(key)) {
             defaults.push(key);
@@ -179,6 +179,6 @@ export function getDefaultFeaturesForResourceType(appType) {
 /**
  * Get all generators for a resource type (for documentation)
  */
-export function getGeneratorsForResourceType(appType) {
-    return Object.values(RESOURCE_FEATURES).filter((f) => f.applies_to.includes(appType));
+export function getGeneratorsForResourceType(resourceType) {
+    return Object.values(RESOURCE_FEATURES).filter((f) => f.applies_to.includes(resourceType));
 }

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

@@ -87,6 +87,7 @@ const GENERATED_STRING_FIELDS = [
         pattern: /^[A-Za-z0-9._/:@-]+$/,
         expected: "an image reference such as ghcr.io/acme/app:1.0",
     },
+    { path: ["basePath"], pattern: /^\/[a-z0-9/-]*$/, expected: "a path such as /storefront" },
 ];
 /**
  * Errors for generated-output fields whose values could change the generated YAML. The value itself is not echoed, because it may

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

@@ -64,6 +64,17 @@ export function resolveServicePath(resource) {
     }
     return resource.config?.basePath ?? `/${resource.name}`;
 }
+/**
+ * The ingress URL of one service (no /health suffix), or undefined for services with no Traefik route. This is where the service
+ * answers, unlike the Tilt UI port, which serves its own page for any path.
+ */
+export function resolveServiceUrl(resource, ingressPort) {
+    const appType = resource.config?.appType;
+    if (appType !== "frontend" && !isApiServiceType(appType))
+        return undefined;
+    const { appBase, apiBase } = resolveSubdomainBases(ingressPort);
+    return `${appType === "frontend" ? appBase : apiBase}${resolveServicePath(resource)}`;
+}
 /**
  * Health URLs for every routable service, matching what `flisk up` prints.
  * Workers, libraries, SDKs and migrators have no Traefik route, so they are

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

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
 import { parseTiltResourceFailures, summarizeTiltBuildError } from "./doctor-runtime.js";
-import { portConflictFix } from "./port-conflict-fix.js";
+import { conflictPort, portConflictFix } from "./port-conflict-fix.js";
 import { effectiveRuntimeStatus, isTiltResourcePending } from "./tilt-resource-state.js";
 import { onlyEnabledResources } from "./up-readiness.js";
 export function transitiveDependencies(name, dependsOn) {
@@ -52,11 +52,12 @@ export function isStartupStalled(jsonText, dependsOn, deferred = new Set()) {
     const report = buildStartupReport(jsonText, dependsOn, deferred);
     return report.failed.length > 0 && report.starting.length === 0;
 }
-export function formatStartupReport(report, timedOut) {
+export function formatStartupReport(report, timedOut, occupantOf) {
     const lines = [];
     for (const { name, message } of report.failed) {
         lines.push(`✗ ${name} failed: ${message}`);
-        const fix = portConflictFix(message);
+        const port = conflictPort(message);
+        const fix = portConflictFix(message, port !== null && occupantOf ? occupantOf(port) : null);
         if (fix)
             lines.push(`  ${fix}`);
     }

package/cli/dist/utils/tar.js

@@ -7,40 +7,45 @@ import { join } from "node:path";
 /**
  * Extracts a gzipped tarball (as an in-memory buffer) into destDir.
  * Shells out to the system `tar` binary rather than pulling in a JS tar
- * implementation - available by default on macOS and Linux.
+ * implementation - available by default on macOS and Linux. On Windows it
+ * runs `tar.exe`, which ships with Windows 10 (1803) and later; see
+ * docs/windows-hardware.md.
  */
 export function extractTarball(data, destDir) {
     const tempDir = mkdtempSync(join(tmpdir(), "flisk-ext-"));
-    const tmpFile = join(tempDir, "bundle.tar.gz");
-    writeFileSync(tmpFile, data);
-    mkdirSync(destDir, { recursive: true });
-    const tarBin = process.platform === "win32" ? "tar.exe" : "tar";
-    const result = spawnSync(tarBin, ["xzf", tmpFile, "-C", destDir, "--strip-components=1"], {
-        stdio: "pipe",
-        windowsHide: true,
-    });
-    if (result.status !== 0) {
-        const fallbackDir = join(tempDir, "fallback");
-        mkdirSync(fallbackDir, { recursive: true });
-        const fallback = spawnSync(tarBin, ["xzf", tmpFile, "-C", fallbackDir], {
+    try {
+        const tmpFile = join(tempDir, "bundle.tar.gz");
+        writeFileSync(tmpFile, data);
+        mkdirSync(destDir, { recursive: true });
+        const tarBin = process.platform === "win32" ? "tar.exe" : "tar";
+        const result = spawnSync(tarBin, ["xzf", tmpFile, "-C", destDir, "--strip-components=1"], {
             stdio: "pipe",
             windowsHide: true,
         });
-        if (fallback.status !== 0) {
-            rmSync(tempDir, { recursive: true, force: true });
-            throw new Error(`tar extraction failed: ${fallback.stderr?.toString() || result.stderr?.toString() || "unknown error"}`);
-        }
-        const entries = readdirSync(fallbackDir);
-        const [only] = entries;
-        const sourceDir = entries.length === 1 &&
-            only !== undefined &&
-            existsSync(join(fallbackDir, only)) &&
-            statSync(join(fallbackDir, only)).isDirectory()
-            ? join(fallbackDir, only)
-            : fallbackDir;
-        for (const entry of readdirSync(sourceDir)) {
-            renameSync(join(sourceDir, entry), join(destDir, entry));
+        if (result.status !== 0) {
+            const fallbackDir = join(tempDir, "fallback");
+            mkdirSync(fallbackDir, { recursive: true });
+            const fallback = spawnSync(tarBin, ["xzf", tmpFile, "-C", fallbackDir], {
+                stdio: "pipe",
+                windowsHide: true,
+            });
+            if (fallback.status !== 0) {
+                throw new Error(`tar extraction failed: ${fallback.stderr?.toString() || result.stderr?.toString() || "unknown error"}`);
+            }
+            const entries = readdirSync(fallbackDir);
+            const [only] = entries;
+            const sourceDir = entries.length === 1 &&
+                only !== undefined &&
+                existsSync(join(fallbackDir, only)) &&
+                statSync(join(fallbackDir, only)).isDirectory()
+                ? join(fallbackDir, only)
+                : fallbackDir;
+            for (const entry of readdirSync(sourceDir)) {
+                renameSync(join(sourceDir, entry), join(destDir, entry));
+            }
         }
     }
-    rmSync(tempDir, { recursive: true, force: true });
+    finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
 }

package/cli/dist/utils/tilt-process.js

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Flisk Landscape contributors
 // SPDX-License-Identifier: MIT
 import { execFileSync } from "node:child_process";
+import { FliskError } from "./errors.js";
 const run = (command, args) => execFileSync(command, args, { encoding: "utf-8", stdio: "pipe", windowsHide: true });
 /** Refuse to target arbitrary listeners: only stop a Tilt process on the requested UI port. */
 export function findTiltProcessIdsOnPort(port, platform = process.platform, commandRunner = run) {
@@ -15,7 +16,7 @@ export function findTiltProcessIdsOnPort(port, platform = process.platform, comm
                 .filter((pid) => Number.isInteger(pid) && pid > 0);
         }
         catch {
-            throw new Error(`Unable to inspect Tilt listeners on port ${port} with PowerShell.`);
+            throw new FliskError(`Unable to inspect Tilt listeners on port ${port} with PowerShell.`, ["Ensure PowerShell is available and accessible"], 1);
         }
     }
     let pids;
@@ -30,7 +31,7 @@ export function findTiltProcessIdsOnPort(port, platform = process.platform, comm
         const stderr = commandErr.stderr?.toString().trim();
         if (commandErr?.status === 1 && !stderr)
             return [];
-        throw new Error(`Unable to inspect listeners on port ${port}. Install lsof or resolve the lsof error before using --force.`, { cause: commandErr });
+        throw new FliskError(`Unable to inspect listeners on port ${port}. Install lsof or resolve the lsof error before using --force.`, ["Install lsof or verify permissions before running with --force"], 1);
     }
     return pids.filter((pid) => {
         try {
@@ -38,7 +39,7 @@ export function findTiltProcessIdsOnPort(port, platform = process.platform, comm
             return name.split(/[\\/]/).at(-1) === "tilt";
         }
         catch (err) {
-            throw new Error(`Unable to identify the process listening on port ${port}.`, { cause: err });
+            throw new FliskError(`Unable to identify the process listening on port ${port}.`, ["Check process inspection permissions"], 1);
         }
     });
 }